{"id":2717,"library":"pysmb","title":"pysmb","description":"pysmb is an experimental SMB/CIFS library written in Python that provides a pure Python implementation of the client-side SMB/CIFS protocol (SMB1 and SMB2). It enables Python applications to access and transfer files to and from SMB/CIFS shared folders, such as Windows file shares and Samba folders. The library is actively maintained, with the current version 1.2.13 released on September 19, 2025, and regular updates.","status":"active","version":"1.2.13","language":"en","source_language":"en","source_url":"https://github.com/miketeo/pysmb","tags":["SMB","CIFS","file sharing","network","Windows","Samba","protocol"],"install":[{"cmd":"pip install pysmb","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for ASN.1 parsing and encoding; needs to be installed separately as it's not bundled with pysmb.","package":"pyasn1","optional":false}],"imports":[{"symbol":"SMBConnection","correct":"from smb.SMBConnection import SMBConnection"}],"quickstart":{"code":"import os\nimport tempfile\nfrom smb.SMBConnection import SMBConnection\n\n# Replace with your SMB server details and credentials\nSERVER_IP = os.environ.get('SMB_SERVER_IP', '127.0.0.1')\nSERVER_NAME = os.environ.get('SMB_SERVER_NAME', 'MYSERVER') # Must match remote machine name\nUSER_ID = os.environ.get('SMB_USER_ID', 'guest')\nPASSWORD = os.environ.get('SMB_PASSWORD', '')\nCLIENT_MACHINE_NAME = os.environ.get('SMB_CLIENT_NAME', 'myclient') # Can be arbitrary\nSHARE_NAME = os.environ.get('SMB_SHARE_NAME', 'public') # Example share name\nREMOTE_FILE_PATH = os.environ.get('SMB_REMOTE_FILE_PATH', '/test.txt') # Path on the share\n\ntry:\n    conn = SMBConnection(USER_ID, PASSWORD, CLIENT_MACHINE_NAME, SERVER_NAME, use_ntlm_v2=True)\n    # Connect to the SMB server on port 445 (direct TCP) or 139 (NetBIOS session service)\n    connected = conn.connect(SERVER_IP, 445)\n\n    if connected:\n        print(f\"Successfully connected to {SERVER_IP} with user {USER_ID}\")\n\n        # Example: List shares (optional, sometimes IPC$ connection errors can occur)\n        try:\n            shares = conn.listShares()\n            print(\"Available shares:\")\n            for share in shares:\n                print(f\"  - {share.name}\")\n        except Exception as e:\n            print(f\"Warning: Could not list shares (this might be expected for some configurations): {e}\")\n\n        # Example: Retrieve a file\n        with tempfile.NamedTemporaryFile(delete=False) as temp_file:\n            file_attributes, filesize = conn.retrieveFile(SHARE_NAME, REMOTE_FILE_PATH, temp_file)\n            print(f\"Retrieved file '{REMOTE_FILE_PATH}' from share '{SHARE_NAME}'. Size: {filesize} bytes.\")\n            print(f\"Local copy saved to: {temp_file.name}\")\n\n        # Always close the connection\n        conn.close()\n        print(\"Connection closed.\")\n    else:\n        print(f\"Failed to connect to {SERVER_IP}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Review the new API documentation for pysmb 1.0.0+ and rewrite code accordingly. There is no direct migration path for 0.x.x code.","message":"pysmb 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.","severity":"breaking","affected_versions":"<1.0.0 to 1.0.0+"},{"fix":"When 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.","message":"In 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()`.","severity":"breaking","affected_versions":"<1.2.0 to 1.2.0+"},{"fix":"Avoid 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.","message":"pysmb 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"It is generally safer to create a new `SMBConnection` instance for each new connection attempt, rather than trying to reuse a closed or failed instance.","message":"Attempting 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.","severity":"gotcha","affected_versions":"All versions, especially Python 3.3+"},{"fix":"Verify 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.","message":"Users 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}