{"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":"en","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,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}