Install & Compatibility
Where this runs
tested against v1.2.15 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.194s · 20.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.178s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SMBConnection
✓ from smb.SMBConnection import SMBConnection
This quickstart demonstrates how to establish an SMB connection, optionally list shares, and retrieve a file from a remote SMB/CIFS server using the `SMBConnection` class. It uses environment variables for sensitive connection details to keep the code runnable without hardcoding credentials.
import os
import tempfile
from smb.SMBConnection import SMBConnection
# Replace with your SMB server details and credentials
SERVER_IP = os.environ.get('SMB_SERVER_IP', '127.0.0.1')
SERVER_NAME = os.environ.get('SMB_SERVER_NAME', 'MYSERVER') # Must match remote machine name
USER_ID = os.environ.get('SMB_USER_ID', 'guest')
PASSWORD = os.environ.get('SMB_PASSWORD', '')
CLIENT_MACHINE_NAME = os.environ.get('SMB_CLIENT_NAME', 'myclient') # Can be arbitrary
SHARE_NAME = os.environ.get('SMB_SHARE_NAME', 'public') # Example share name
REMOTE_FILE_PATH = os.environ.get('SMB_REMOTE_FILE_PATH', '/test.txt') # Path on the share
try:
conn = SMBConnection(USER_ID, PASSWORD, CLIENT_MACHINE_NAME, SERVER_NAME, use_ntlm_v2=True)
# Connect to the SMB server on port 445 (direct TCP) or 139 (NetBIOS session service)
connected = conn.connect(SERVER_IP, 445)
if connected:
print(f"Successfully connected to {SERVER_IP} with user {USER_ID}")
# Example: List shares (optional, sometimes IPC$ connection errors can occur)
try:
shares = conn.listShares()
print("Available shares:")
for share in shares:
print(f" - {share.name}")
except Exception as e:
print(f"Warning: Could not list shares (this might be expected for some configurations): {e}")
# Example: Retrieve a file
with tempfile.NamedTemporaryFile(delete=False) as temp_file:
file_attributes, filesize = conn.retrieveFile(SHARE_NAME, REMOTE_FILE_PATH, temp_file)
print(f"Retrieved file '{REMOTE_FILE_PATH}' from share '{SHARE_NAME}'. Size: {filesize} bytes.")
print(f"Local copy saved to: {temp_file.name}")
# Always close the connection
conn.close()
print("Connection closed.")
else:
print(f"Failed to connect to {SERVER_IP}")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingpysmb version 1.0.0 introduced a complete rewrite of the library, making its API incompatible with previous versions (0.x.x). Applications written for 0.x.x will need significant updates.fixReview the new API documentation for pysmb 1.0.0+ and rewrite code accordingly. There is no direct migration path for 0.x.x code.
affects: <1.0.0 to 1.0.0+
breakingIn pysmb 1.2.0, the `deleteFiles()` and `storeFileFromOffset()` methods in `SMBProtocolFactory` and `SMBConnection` classes were updated. The `timeout` parameter now requires a named argument, and a new `delete_matching_folders` parameter was added to `deleteFiles()`.fixWhen calling `deleteFiles()` or `storeFileFromOffset()`, ensure the `timeout` parameter is passed as `timeout=value` (e.g., `conn.deleteFiles('share', '/path', timeout=30)`). If deleting folders, consider the `delete_matching_folders` parameter. affects: <1.2.0 to 1.2.0+
gotchapysmb can conflict with other libraries like `impacket` if both are installed in the same environment, as they might both contain a file named `smbconnection.py`. This can lead to import errors or unexpected behavior due to name collisions.fixAvoid installing `pysmb` and `impacket` in the same Python environment. Use separate virtual environments for projects that depend on either library, or carefully manage your `PYTHONPATH` if absolutely necessary.
affects: All versions
gotchaAttempting to reuse an `SMBConnection` instance by calling `connect()` again after a `close()` call (or a previous failed connection) might lead to an `UnboundLocalError` or `Connection reset by peer` errors. The connection state is not always properly reset for reuse.fixIt is generally safer to create a new `SMBConnection` instance for each new connection attempt, rather than trying to reuse a closed or failed instance.
affects: All versions, especially Python 3.3+
gotchaUsers might encounter `smb.smb_structs.OperationFailure: Failed to list shares: Unable to connect to IPC$` when attempting to list shares. This error often indicates underlying network configuration issues, incorrect permissions, or server-side restrictions on accessing the IPC$ share, rather than a bug within `pysmb` itself.fixVerify the SMB server's network accessibility, firewall rules, user permissions for accessing shares (especially IPC$), and ensure that the server's NetBIOS name or IP address is correct. Test access from other SMB clients if possible.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'smb'
The pysmb library is not installed in the current Python environment, or the import statement is incorrect.
fixInstall the library using pip: `pip install pysmb`. Then, use the correct import statement: `from smb.SMBConnection import SMBConnection`.
SMB_Error: STATUS_LOGON_FAILURE
The username, password, or domain provided for authentication to the SMB share is incorrect or the user lacks necessary permissions.
fixVerify the exact username, password, and domain (if used) passed to the `SMBConnection` constructor and ensure the user has appropriate permissions on the target SMB share.
socket.error: [Errno 111] Connection refused
The SMB server is not reachable, its SMB service is not running, or a firewall is blocking the connection on the client or server side.
fixCheck the target host IP/hostname, confirm the SMB server is running and accessible, and ensure no firewalls are blocking SMB ports (typically 139 and 445).
SMB_Error: NT_STATUS_OBJECT_NAME_NOT_FOUND
The specified share name, directory path, or file name does not exist on the SMB server, or the path is incorrect.
fixDouble-check the spelling and full path of the share, directory, or file on the remote SMB server, paying attention to case sensitivity and correct delimiters.
Upgrade
Version history
1.2.15latest on PyPI · released Aug 8, 2026
Audit
Dependencies
pyasn1requiredRequired for ASN.1 parsing and encoding; needs to be installed separately as it's not bundled with pysmb.