Registry / database / smbprotocol

smbprotocol

JSON →
library1.17.0pypypi✓ verified 25d ago

smbprotocol is a Python library designed to interact with servers using the SMB 2/3 Protocol. It provides low-level access to SMB operations, allowing for file and directory manipulation, session management, and authentication against SMB/CIFS shares. The current version is 1.16.1, and the project maintains an active release cadence with multiple updates per year.

pip install smbprotocol
INSTALL
IMPORT
SIG · SMBPROTOCOL
S
smbprotocol
databasepythonv1.17.0
Install
2.6s avg
Import
112ms
Disk
35MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.17.0 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.116s · 37MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.6s · import 0.108s · 37MB
35MB installed
● package 35MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Connection
from smbprotocol.connection import Connection
Session
from smbprotocol.session import Session
TreeConnect
from smbprotocol.tree import TreeConnect
Open
from smbprotocol.open import Open
FilePipe
from smbprotocol.file import FilePipe
CreateDisposition
from smbprotocol.file import CreateDisposition

This quickstart demonstrates how to establish a connection to an SMB server, authenticate a user, connect to a shared folder, and list its contents. It emphasizes the critical need to explicitly close all resources (Connection, Session, TreeConnect, Open objects) in a `finally` block to prevent resource leaks.

import os from smbprotocol.connection import Connection from smbprotocol.session import Session from smbprotocol.tree import TreeConnect from smbprotocol.open import Open, CreateDisposition # Replace with your SMB server details SERVER_IP = os.environ.get('SMB_SERVER_IP', '127.0.0.1') USERNAME = os.environ.get('SMB_USERNAME', 'guest') PASSWORD = os.environ.get('SMB_PASSWORD', '') SHARE_NAME = os.environ.get('SMB_SHARE_NAME', 'share') # e.g., 'myshare' def list_share_contents(): connection = None session = None tree_connect = None try: print(f"Connecting to {SERVER_IP}...") connection = Connection(SERVER_IP, port=445) connection.connect() print("Connection established.") print(f"Authenticating as {USERNAME}...") session = Session(connection, USERNAME, PASSWORD) session.connect() print("Authentication successful.") print(f"Connecting to share \\{SERVER_IP}\{SHARE_NAME}...") # SMB paths use backslashes, but smbprotocol handles forward slashes too tree_connect = TreeConnect(connection, session, f'\\\\{SERVER_IP}\\{SHARE_NAME}') tree_connect.connect() print(f"Connected to share '{SHARE_NAME}'.") print(f"Listing contents of '{SHARE_NAME}':") # Open the directory itself to enumerate its contents dir_open = Open(tree_connect, '/*', CreateDisposition.FILE_OPEN, access_mask=0x80000000) # FILE_LIST_DIRECTORY dir_open.create() for entry in dir_open.query_directory(): print(f" - {entry.file_name}") dir_open.close() except Exception as e: print(f"An error occurred: {e}") finally: if tree_connect: print("Disconnecting from tree connect...") tree_connect.disconnect() if session: print("Logging off session...") session.logoff() if connection: print("Disconnecting connection...") connection.disconnect() print("Cleanup complete.") if __name__ == '__main__': list_share_contents()
Debug
Known issues
breakingSMBv1 (Server Message Block version 1) support was completely removed starting from smbprotocol version 1.0.0. This library now exclusively supports SMBv2 and SMBv3.
fix
Ensure your SMB server supports SMBv2 or SMBv3. If you are connecting to older systems (e.g., Windows XP, Windows Server 2003 without updates), you will need to upgrade the server or use a different library.
affects: 1.0.0 and newer
gotchaAll `smbprotocol` objects representing server resources (e.g., `Connection`, `Session`, `TreeConnect`, `Open`) require explicit disconnection or closing. Failing to call `.disconnect()` or `.close()` will lead to resource leaks on both the client and server.
fix
Always wrap your `smbprotocol` operations in `try...finally` blocks to ensure that `.disconnect()` or `.close()` methods are called for all instantiated resource objects. For file-like objects, consider using a `with` statement if available (e.g., `smbprotocol.file.File` does support `with`).
affects: All versions
gotchaAuthentication can be complex, especially with Active Directory domains or specific security policies. Incorrectly providing the username (e.g., missing domain prefix for domain accounts, using UPN instead of samAccountName) or incorrect password hashing can lead to failed connections.
fix
Verify the exact username format required by your SMB server (e.g., `DOMAIN\username`, `username@domain.com`, or just `username` for local accounts). Ensure the password is correct. For Active Directory, you might need to ensure proper DNS resolution and Kerberos setup if using Kerberos authentication.
affects: All versions
gotchaThe `smbprotocol` library provides a synchronous API. While it can be used within an `asyncio` application, it does not directly support `await` and will block the event loop if not run in a separate thread or process.
fix
If integrating into an `asyncio` application, use `loop.run_in_executor()` to run `smbprotocol` calls in a separate thread pool to prevent blocking the main event loop.
affects: All versions
Errors
Common errors & fixes
smbprotocol.exceptions.SMB2UnsuccessfulResponse: [Error 3221225581] STATUS_LOGON_FAILURE
The provided username, password, or domain is incorrect, or the account is disabled/locked out on the SMB server.
fix
Double-check the credentials, ensure the user account is active, and confirm the domain is specified correctly if required for authentication.
OSError: [Errno 111] Connection refused
The SMB server is not running, is unreachable, or a firewall is blocking the connection on either the client or server side.
fix
Verify the server's IP address/hostname and port (default 445), check local and server firewall rules, and ensure the SMB service is active on the server.
smbprotocol.exceptions.SMB2UnsuccessfulResponse: [Error 3221225524] STATUS_OBJECT_NAME_NOT_FOUND
The specified file or directory path does not exist on the SMB share or contains a typo.
fix
Verify the exact path on the SMB share, ensuring correct spelling and case sensitivity, and confirm the object exists.
smbprotocol.exceptions.SMB2UnsuccessfulResponse: [Error 3221225506] STATUS_ACCESS_DENIED
The authenticated user account lacks the necessary permissions to perform the requested operation (e.g., read, write, delete) on the target file or directory.
fix
Ensure the authenticated user account has the required permissions on the specific SMB share and the target file/directory.
Upgrade
Version history
1.17.0latest on PyPI · released Jul 7, 2026
Audit
Dependencies
pyspnegorequiredProvides NTLM and Kerberos authentication capabilities, which smbprotocol relies on for secure connections.
Agent activity
46 hits · last 30 days
node
40
Meta
2
Amazon
1
OpenAI (training)
1
Resources
smbprotocol — pip install smbprotocol · libregistry