smbprotocol

For most common use cases, use the smbclient interface. It provides a high-level API that replicates Python's built-in os and os.path functions (e.g., mkdir, open_file, stat, exists).

Key features of smbclient:

• Connection Pooling: Connections are pooled and reused for the same server during the Python process lifetime.
• DFS Support: Automatically handles DFS (Distributed File System) targets and caches referrals.
• Simplified Auth: Authentication is typically only required for the first call to a server.

import smbclient

# Example usage
smbclient.mkdir(r"\\server\share\directory", username="user", password="pass")

with smbclient.open_file(r"\\server\share\directory\file.txt", mode="w") as fd:
    fd.write(u"file contents")

Install the base package using pip:

pip install smbprotocol

If you require Kerberos authentication support, install the package with the [kerberos] extra. Note that on Linux, additional system dependencies (like libkrb5-dev) must be installed via your package manager first.

To use Kerberos authentication on Linux, you must install system-level development headers before installing the Python package.

For Debian/Ubuntu/etc:

sudo apt-get install gcc python-dev libkrb5-dev
pip install smbprotocol[kerberos]

For RHEL/CentOS/etc:

sudo yum install gcc python-devel krb5-devel krb5-workstation python-devel
pip install smbprotocol[kerberos]

You can verify if the required python-gssapi extension is available by running this check in a Python console:

# for Debian/Ubuntu/etc:
sudo apt-get install gcc python-dev libkrb5-dev
pip install smbprotocol[kerberos]

# for RHEL/CentOS/etc:
sudo yum install gcc python-devel krb5-devel krb5-workstation python-devel
pip install smbprotocol[kerberos]

If you are using Linux, run the following snippet in a Python console to ensure the python-gssapi extension is correctly installed and available. If this fails, the library will fallback to NTLM authentication.

try:
    from gssapi.raw import inquire_sec_context_by_oid
    print("python-gssapi extension is available")
except ImportError as exc:
    print(f"python-gssapi extension is not available: {exc}")

The smbclient.ClientConfig singleton allows you to set global connection defaults for all future smbclient calls. Updating the singleton updates the settings for all subsequent operations.

import smbclient

smbclient.ClientConfig(username='user', password='password')

You can manage how credentials and connections are handled in smbclient using the following methods:

• Register a session: Use smbclient.register_session("server", username="...", password="...") to associate specific credentials with a server. This overrides the global ClientConfig for that specific server.
• Reset cache: Use smbclient.reset_connection_cache() to close all currently cached connections.

import smbclient

# Set global defaults
smbclient.ClientConfig(username='user', password='pass')

# Register specific credentials for a specific server (overrides ClientConfig)
smbclient.register_session("server", username="user", password="pass")

# Reset all cached connections
smbclient.reset_connection_cache()

By default, smbprotocol negotiates the latest dialect supported by the server. You can manually override this to set a minimum dialect version using the Connection object and the Dialects enum.

import uuid

from smbprotocol.connection import Connection, Dialects

connection = Connection(uuid.uuid4(), "server", 445)
connection.connect(Dialects.SMB_3_0_2)

The Connection object uses an experimental receive timeout for the transport. This can be configured using the following environment variable:

SMB_EXPERIMENTAL_TRANSPORT_RECEIVE_TIMEOUT: Integer value in seconds (defaults to 600).

The following keys can be set on the smbclient.ClientConfig singleton to define global connection behavior:

• client_guid: The client GUID to identify the client to the server on a new connection.
• username: The default username to use when creating a new SMB session if explicit credentials weren't set.
• password: The default password to use for authentication.
• domain_controller: The domain controller hostname. Useful for DFS environments to identify domain information automatically.
• skip_dfs: Whether to skip DFS resolution (useful for bypassing bugs or reducing roundtrips).
• auth_protocol: The authentication protocol to use; options are negotiate (default), kerberos, or ntlm.
• require_secure_negotiate: Control whether the client validates negotiation info (default: True).

Individual smbclient functions (like open_file, mkdir, etc.) accept the following keyword arguments to override global configuration or specify connection parameters:

• username: The username used to connect to the share.
• password: The password used to connect to the share.
• port: Override the default port (445).
• encrypt: Whether to force encryption on the connection (requires SMBv3+ on the server; default: False).
• connection_timeout: Override the connection timeout in seconds (default: 60).