{"id":1713,"library":"smbprotocol","title":"SMB Protocol Library","description":"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.","status":"active","version":"1.16.1","language":"python","source_language":"en","source_url":"https://github.com/jbogard93/smbprotocol","tags":["smb","protocol","network","file-sharing","windows"],"install":[{"cmd":"pip install smbprotocol","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides NTLM and Kerberos authentication capabilities, which smbprotocol relies on for secure connections.","package":"pyspnego","optional":false}],"imports":[{"symbol":"Connection","correct":"from smbprotocol.connection import Connection"},{"symbol":"Session","correct":"from smbprotocol.session import Session"},{"symbol":"TreeConnect","correct":"from smbprotocol.tree import TreeConnect"},{"symbol":"Open","correct":"from smbprotocol.open import Open"},{"symbol":"FilePipe","correct":"from smbprotocol.file import FilePipe"},{"symbol":"CreateDisposition","correct":"from smbprotocol.file import CreateDisposition"}],"quickstart":{"code":"import os\nfrom smbprotocol.connection import Connection\nfrom smbprotocol.session import Session\nfrom smbprotocol.tree import TreeConnect\nfrom smbprotocol.open import Open, CreateDisposition\n\n# Replace with your SMB server details\nSERVER_IP = os.environ.get('SMB_SERVER_IP', '127.0.0.1')\nUSERNAME = os.environ.get('SMB_USERNAME', 'guest')\nPASSWORD = os.environ.get('SMB_PASSWORD', '')\nSHARE_NAME = os.environ.get('SMB_SHARE_NAME', 'share') # e.g., 'myshare'\n\ndef list_share_contents():\n    connection = None\n    session = None\n    tree_connect = None\n    try:\n        print(f\"Connecting to {SERVER_IP}...\")\n        connection = Connection(SERVER_IP, port=445)\n        connection.connect()\n        print(\"Connection established.\")\n\n        print(f\"Authenticating as {USERNAME}...\")\n        session = Session(connection, USERNAME, PASSWORD)\n        session.connect()\n        print(\"Authentication successful.\")\n\n        print(f\"Connecting to share \\\\{SERVER_IP}\\{SHARE_NAME}...\")\n        # SMB paths use backslashes, but smbprotocol handles forward slashes too\n        tree_connect = TreeConnect(connection, session, f'\\\\\\\\{SERVER_IP}\\\\{SHARE_NAME}')\n        tree_connect.connect()\n        print(f\"Connected to share '{SHARE_NAME}'.\")\n\n        print(f\"Listing contents of '{SHARE_NAME}':\")\n        # Open the directory itself to enumerate its contents\n        dir_open = Open(tree_connect, '/*', CreateDisposition.FILE_OPEN, access_mask=0x80000000) # FILE_LIST_DIRECTORY\n        dir_open.create()\n\n        for entry in dir_open.query_directory():\n            print(f\"  - {entry.file_name}\")\n        dir_open.close()\n        \n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n    finally:\n        if tree_connect:\n            print(\"Disconnecting from tree connect...\")\n            tree_connect.disconnect()\n        if session:\n            print(\"Logging off session...\")\n            session.logoff()\n        if connection:\n            print(\"Disconnecting connection...\")\n            connection.disconnect()\n        print(\"Cleanup complete.\")\n\nif __name__ == '__main__':\n    list_share_contents()","lang":"python","description":"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."},"warnings":[{"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.","message":"SMBv1 (Server Message Block version 1) support was completely removed starting from smbprotocol version 1.0.0. This library now exclusively supports SMBv2 and SMBv3.","severity":"breaking","affected_versions":"1.0.0 and newer"},{"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`).","message":"All `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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Authentication 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.16.1':45 '2/3':17 'access':24 'activ':51 'allow':28 'authent':37 'cadenc':53 'current':42 'design':9 'directori':32 'file':30,63 'file-shar':62 'interact':11 'level':23 'librari':3,8 'low':22 'low-level':21 'maintain':49 'manag':35 'manipul':33 'multipl':55 'network':61 'oper':27 'per':57 'project':48 'protocol':2,18,60 'provid':20 'python':7 'releas':52 'server':13 'session':34 'share':40,64 'smb':1,16,26,59 'smb/cifs':39 'smbprotocol':4 'updat':56 'use':14 'version':43 'window':65 'year':58","created_at":"2026-04-09T03:59:56.456462+00:00","updated_at":"2026-04-16T21:50:47.654790+00:00","problems":[{"fix":"Double-check the credentials, ensure the user account is active, and confirm the domain is specified correctly if required for authentication.","cause":"The provided username, password, or domain is incorrect, or the account is disabled/locked out on the SMB server.","error":"smbprotocol.exceptions.SMB2UnsuccessfulResponse: [Error 3221225581] STATUS_LOGON_FAILURE"},{"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.","cause":"The SMB server is not running, is unreachable, or a firewall is blocking the connection on either the client or server side.","error":"OSError: [Errno 111] Connection refused"},{"fix":"Verify the exact path on the SMB share, ensuring correct spelling and case sensitivity, and confirm the object exists.","cause":"The specified file or directory path does not exist on the SMB share or contains a typo.","error":"smbprotocol.exceptions.SMB2UnsuccessfulResponse: [Error 3221225524] STATUS_OBJECT_NAME_NOT_FOUND"},{"fix":"Ensure the authenticated user account has the required permissions on the specific SMB share and the target file/directory.","cause":"The authenticated user account lacks the necessary permissions to perform the requested operation (e.g., read, write, delete) on the target file or directory.","error":"smbprotocol.exceptions.SMB2UnsuccessfulResponse: [Error 3221225506] STATUS_ACCESS_DENIED"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.17.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jborean93/smbprotocol","docs":null,"changelog":null,"pypi":"https://pypi.org/project/smbprotocol/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":null}}