pysmb

pysmb is an experimental SMB/CIFS library written in Python. It implements the client-side SMB/CIFS protocol (SMB1 and SMB2) which allows your Python application to access and transfer files to/from SMB/CIFS shared folders like your Windows file sharing and Samba folders.

If you use pysmb in your applications, please drop me a comment at the bottom of this page to let me and the others know of what you have done using pysmb. Thanks.

For bug reports, please access the issue tracker on github.

For the latest code under development or if you wish to help out with pysmb development, please visit the pysmb repository on github.

What It Can Do

From version 1.0.0, pysmb has been completely rewritten and has been tested to be able to login to and upload/download files from shared folders on Samba, Windows XP, Windows Vista and Windows 7 machines. For more information on how to write your own file transfer applications using pysmb, please refer to the online documentation at readthedocs.org or check out the documentation in the 1.0 source files.

What It Can't Do

Note that this is only a client library. It does not share files.

Downloads

If you have problems opening tar.gz files in Windows, please install 7-Zip. It supports 7z, ZIP, GZIP, BZIP2, TAR and many other archive formats.

Version 1.2.10, 2024-09-25 (Download)

  • Fix a bug where the OperationFailure exceptions do not contain the error messages that were thrown when the exception occurred. Thanks to Armann7 (github) for the fix.
  • Update test cases to replace SafeConfigParser with ConfigParser. Thanks to badshah400 (github) for the patch.
  • Allow callers to override default tqdm kwargs.Thanks to chausner (github) for the patch.

Version 1.2.9, 2022-12-25 (Download)

  • Add support for tqdm progress display. Thanks to edugzlez (github) for the patch.
  • Fix bug where timeout parameter was not passed to socket.createConnection(). Thanks to lff5 (github) for the fix.

Version 1.2.8, 2022-06-12 (Download)

  • Fix issue with listPath based on recommendation from ArtemUstynov (github).
  • Fix embedded MD4 algorithm. Thanks to zentarim (github) for the patch.
  • Add SMB UTF-16 surrogate exception workaround policy. Thanks to joshlin5900 (github) for the patch.

Version 1.2.7, 2021-05-30 (Download)

  • Fix compatibility issues on file retrievals with Likewise servers. Thanks to viralmutant (github) for the fix.
  • Improve SMBConnection's connect() method to remove the need to provide sock_family parameter for IPv6 addresses in Python 3.x. Thanks to frafra (github) for the patch.

Version 1.2.6, 2020-10-06 (Download)

  • Fix bug in SMB1 store file implementation which generates SMB_COM_WRITE_ANDX packets larger than the allowed max buffer size. Thanks to DjesLoc (github) for helping to troubleshoot and test the fix before release.

Version 1.2.5, 2020-10-18 (Download)

  • Fix bug in filename encoding which leads to failure for file retrieval and upload operations. Contributed by theoharr (github).
  • Improve resetFileAttributes() method in SMBConnection class to allow the new attribute to be specified in the reset operation. Contributed by benmoran56 (github).

Version 1.2.4, 2020-10-06 (Download)

  • Remove dependency on pycrypto. Thanks to carno (github) for bringing pycrypto's status to my attention.

Version 1.2.3, 2020-10-06 (Download)

  • Fix bug in session key generation during session negotiation. Contributed by theoharr (github) and PLanB2008 (github)
  • Fix bug in SMB message signing which leads to operation failures with Samba services.

Version 1.2.2, 2020-09-05 (Download)

  • Improve SMB URLs to support specifying server's machine name and IP address. Contributed by christopherpickering (github).
  • Improve documentation on SMB URLs

Version 1.2.1, 2020-05-17 (Download)

  • Fix bug in deleteFiles() method which can fail for certain search patterns.

Version 1.2.0, 2020-05-17 (Download)

  • Improve deleteFiles() API to support deleting child folders that match the search pattern

Version 1.1.29, 2020-05-16 (Download)

  • Fix unhandled exception for short NBNS queries.
  • Fix wildcard file deletion with servers on SMB2 protocol.

Version 1.1.28, 2019-11-23 (Download)

  • SharedFile instances returned from the listPath() method now has a new file_id attribute which represents the file reference number given by the SMB server. Contributed by electricbrew (github)

Version 1.1.27, 2019-01-09 (Download)

  • Remove support for SMB-2.1 dialect which could be causing compatibility issues with Windows 2008 R2.

Version 1.1.26, 2019-01-05 (Download)

  • Prevents OperationError from being raised when listPath() operation does not return any matching file results.
  • SMBConnection is now a context manager

Version 1.1.25, 2018-07-28 (Download)

  • Fix buggy support for search parameter in listPath() method. Add SMB_FILE_ATTRIBUTE_INCL_NORMAL bit constant to include 'normal' files with other file types in the returned result. From now on, pysmb defines a 'normal' file as a file entry that is not read-only, not hidden, not system, not archive and not a directory; it ignores other attributes like compression, indexed, sparse, temporary and encryption. listPath() method will now include 'normal' files using the default search parameter.
  • Add isNormal property to SharedFile class to support test if the file is a 'normal' file (according to pysmb definition of 'normal' file).

Version 1.1.24, 2018-07-19 (Download)

  • Improve listPath implementation for SMB1
  • Support for STATUS_PENDING responses across all SMB2 operations.

Version 1.1.23, 2018-05-05 (Download)

  • Fix bug in listShares() method which fails when the remote server has many shares. Contributed by carlosefr (github).
  • Improve echo() method to test and fail if the provided data to echo is not a bytes object. Contributed by carlosefr (github).
  • Fix bug in listPath() method where the path to query is not properly terminated. Contributed by Yepoleb (github).

Version 1.1.22, 2017-09-17 (Download)

  • Fix bug in getAttributes() method which should return only the filename instead of the entire path for the filename property for the return result.

Version 1.1.21, 2017-09-09 (Download)

  • Fix bug where timestamp values for SMB1 getAttributes() response are not converted properly from FILETIME to epoch time values.

Version 1.1.20, 2017-08-13 (Download)

  • Add getSecurity() method to support security descriptors query via SMB2. Contributed by koniiiik (github).
  • Improve retrieveFile() and retrieveFileFromOffset() methods to allow file retrievals over SMB2 even when the file is being locked on the server.
  • Silently discards NMB SESSION_KEEPALIVE packets instead of raising warnings. Thanks to a-mushroom (github) for reporting this.
  • SMB sessionID will be sent in ECHO requests to conform to SMB2 specs. Thanks to divad (github) for reporting this.
  • Fix type errors for MD4 functions in python3. Contributed by viatoriche (github).

Version 1.1.19, 2016-11-13 (Download)

  • Ignore STATUS_PENDING during delete and file store operations

Version 1.1.18, 2016-04-09 (Download)

  • Rollback fixes to NTLMv2 response algorithm in pysmb 1.1.17. The fixes fail to work with some servers.
  • Add missing errno imports in SMBConnection.py
  • Fix UnboundLocalError raised when using type() in SMBConnection.py

Version 1.1.17, 2015-11-11 (Download)

  • Fix crashes in directory listing with keyerror 'support_dfs'.
  • Fix bugs in NTLMv2 response algorithm.
  • Fix bugs where client domain is not included as part of the session negotiation.

Version 1.1.16, 2015-05-10 (Download)

  • Fix typo errors in authentication error messages.
  • Improve share listings on SMB2 protocol by ignoring interim STATUS_PENDING responses.

Version 1.1.15, 2015-02-15 (Download)

  • Add new parameter to SMBConnection's storeFileFromOffset method to determine whether the remote file is to be truncated before writing.

Version 1.1.14, 2015-02-01 (Download)

  • Add support for DFS shares in listPath(). Thanks to humberry (github) for raising the issue and helping with the testing.
  • Fix bug in python3's SMB2 listPath implementation. Thanks to deejrose (github) for reporting the bug.

Version 1.1.13, 2014-10-18 (Download)

  • Add missing methods and improve compatibility with python3. Thanks to keisetsu (github) for submitting the patch.
  • Fix bug in SMB2 rename implementation which fails to rename directory. Thanks to Jayke Meijer for raising the bug and providing the packet capture.

Version 1.1.12, 2014-09-21 (Download)

  • Fix syntax error for python3 NBNSProtocol implementation
  • Fix bug in SMB1 implementation which results in access denied errors with Samba 3.0. Many thanks for John Sivak for his assistance and support in helping to troubleshoot and test the bug fixes.

Version 1.1.11, 2014-09-13 (Download)

  • Add support for unicode characters in domain, username and password.
  • Add storeFileFromOffset method to SMB API
  • Fix bug in getAttributes implementation for SMB1
  • Fix bug for NMB which uses broadcast flag for unicast queries
  • Update the Tree Connect Andx request implementation to support MS-SMB 2.2.4.7.1 extensions

Version 1.1.10, 2014-06-29 (Download)

  •  Add getAttributes() method to SMBConnection and SMBProtocolFactory class.
  • Add isReadOnly property to SharedFile class.

Version 1.1.9, 2014-06-01 (Download)

  • Add support for domains in smb:// URLs. Contributed by Andy Piper.
  • Fix a bug which fails to test for the correct GSS security provider OID values. Thanks for Fanen for bug report and assistance in testing the fix.

Version 1.1.8, 2013-12-21 (Download)

  • Fix a bug in storeFile() method when the destination file is not overwritten if it exists in SMB1 communication. Thanks to Vaikar Amol for reporting this bug and helping to fix it.
  • Fix a SMB1 authentication problem when extended negotation is not carried out because the remote server has specified its support for extended security in the payload, instead of in the message flags2.

Version 1.1.7, 2013-09-27 (Download)

  • Improve listShares() function which can fail with the listing response is separated into multiple SMB packets for large number of shares. Thanks to Pieter De Clerck for reporting this bug and helping to test the bug fix.
  • Fix bug in python3 implementation where session connection can fail when remote server supports message signing. Thanks to Simon for reporting this bug.

Version 1.1.6, 2013-08-16 (Download)

  • Fix bug where the status of the SMB_COM_NEGOTIATE reply is not checked for error before allowing further processing. Thanks to Adrian Cox for discovering this bug and submitting the patch.

Version 1.1.5, 2013-06-19 (Download)

  • Add support for Direct hosting of SMB over TCP/IP (TCP port 445)

Version 1.1.4, 2013-05-31 (Download)

  • Improve query performance for query IP addresses for NetBIOS names in NetBIOSProtocol.py. Thanks to Ties de Kock for submitting the performance patch.
  • Fix bugs in SMBConnection when sending large data packets can result in AssertionError. Thanks to David K. Hess for submitting the bug fix.

Version 1.1.3, 2013-03-18 (Download)

  • Fix a bug which results in endless loop in SMBConnection when remote CIFS server closes the connection. Thanks to Nitin Garg for submitting the bug fixes.

Version 1.1.2, 2012-09-28 (Download)

  • Improve queryIPForName() in nmb.NetBIOS and nmb.NBNSProtocol class to return only server machine name and ignore workgroup names.

Version 1.1.1, 2012-06-09 (Download)

  • Adds support for Python3. Noted that the Python3 SMB/NMB protocol implementations for Twisted are not well-tested as Twisted (as of v12.1) is not Python3 ready yet.
  • Adds support for retrieving list of shadow copies (also known as "previous versions" in Windows). Note that not all Windows editions support shadow copies.

Version 1.1.0, 2012-06-01 (Download)

  • Adds SMB2 protocol implementation with signing for outgoing SMB2 messages. pysmb will utilize SMB2 protocol with servers that support SMB2 protocol (eg. Windows Vista, Windows 7 and Samba 3). If the remote server does not support SMB2, pysmb will fall back automatically to using SMB1 protocol.

Version 1.0.5, 2012-05-07 (Download)

  • Add supports for SMB message signing. pysmb can sign SMB messages from the CIFS client to the server, but it does not verify the signatures of the SMB messages from the server.

Version 1.0.4, 2012-05-01 (Download)

  • Adds support for "smb://" URL in urllib2 python packages to retrieve or upload files from/to remote CIFS servers.
  • Improve documentation

Version 1.0.3, 2012-04-28 (Download)

  • Fix a crash in SMB._storFile() method which occurs when the remote CIFS server utilizes a max raw size larger than 65535 bytes. The bug was discovered with Windows 7 Pro SP1. Thanks to Bram Deprettere for submitting the bug report.
  • Fix a bug in SMB._listPath() method where the files/folders time information are not properly converted to Epoch time. Thanks to John Lau for discovering this bug.
  • Add NBNSProtocol.queryIPForName() and NetBIOS.queryIPForName() methods to query for a machine's NetBIOS name at the given IP address. Thanks to Jason Anderson for providing the initial implementation.
  • Add SMBProtocol.retrieveFileFromOffset() and SMBConnection.retrieveFileFromOffset() methods for a finer control of file retrieval operation with read offset and write limits.

Version 1.0.2, 2012-03-25 (Download)

  • Fix a bug in SMB._handleSessionChallenge() method in base.py where the domain attribute was not used to generate the corresponding NTLM authentication packets, resulting in the default WORKGROUP domain for used for all subsequent authentications. Thanks to John Lau for submitting the bug report.

Version 1.0.1, 2012-01-25 (Download)

  • Fixes a bug in listPath() method which causes directory listing for sub-directories to return an empty list.
  • Fixes an incorrect implementation of the TRANS2_FIND_FIRST2 and TRANS2_FIND_NEXT2 request/response handling which causes directory listing to crash when the remote directory contains a certain number of entries.

Version 1.0.0a, 2011-12-30 (Download)

  • Completely rewrites pysmb. API is not compatible with previous pysmb-0.x.x
  • Supports NTLMv1 and NTLMv2 authentication
  • Adds in NMB/SMB protocol implementation for use with Twisted framework
  • Tested with Windows XP SP3, Windows Vista, Windows 7 and Samba 3.x
  • Requires Python 2.4.4 or later, and pyasn1. Not tested with Python3
  • Fixes a bug in previous release (1.0.0) where the package was not built properly and had missing files. (Many thanks to Adrian Klaver for pointing this out)

Version 0.4.5, 2009-06-22 (Download)

  • Prevents pysmb from failing when there are too many files/folders to be returned in a single SMB TRANS2 call. pysmb will "resume" requesting for more files/folders information in subsequent SMB TRANS2 requests.

Version 0.4.4, 2004-01-12 (Download)

  • Add in support for AMK's Python Cryptography Toolkit which will be used for DES password hashing. If AMK's pycrypto is found, it will be used instead of mxCrypto.

Version 0.4.3, 2003-02-22 (Download)

  • Fix a bug which fails to close the socket in nmb.py on socket exception
  • Fix a bug which fails to close the NetBIOSSession in smb.py if the session has not been properly established yet

Version 0.4.2, 2002-08-03 (Download)

  • Add new methods to SharedFile instances, get_mtime_epoch, get_atime_epoch and get_ctime_epoch. These methods will return the mtime, atime and ctime in epoch time rather than SMB time.
  • Remove debugging printout in smb.py which has been released accidentally with the last release.
  • Fix a bug in smbcp which causes to local to remote copy to fail

Version 0.4.1, 2002-06-22 (Download)

  • Fix a bug in smb.py which does not return the correct file size for files with their archive bits turned off. This results in these files not being retrieved or sent properly.
  • Fix some typo error in the documentations

Version 0.4.0, 2002-04-17 (Download)

  • Use NT LM0.12 dialect.
  • New smb.SMBMachine class
  • Add SMB.get_server_domain(), smb.get_server_os(), SMB.get_server_lanman()

Version 0.3.1, 2001-11-12 (Download)

  • Fix a problem with some Windows server where an UID is required when server is in share mode.  Now, pysmb calls login() with empty authentication information when server is in share mode.
  • Add TYPE_DOMAIN_MASTER constant and description to nmb.py.

Version 0.3.0, 2001-11-10 (Download)

  • Add support for services in share mode. Minor changes to smb.SMB class API.
  • Fix a bug in smb.py's __raw_retr_file which has failed to initialize the max_buf_size prior to usage.
  • Fix a bug in smblistshare which fails to print the correct NMB error message
  • Modify smb.py not throw AttributeError in the destructor when there is an error while creating a session in the constructor

Version 0.2.0, 2001-10-04 (Download)

  • Add support for encrypted authentication using DES
  • Fix a bug(?) which treats all services and filenames as case-sensitive

Version 0.1.3, 2001-09-03 (Download)

  • Fix a bug in smblistshare and smbdu which fails to catch the nmb.NetBIOSError raised when session setup fails.
  • Fix a bug in smb.SMB that arises from the change in nmb.NetBIOSSession which sends the session port number as the remote host type.

Version 0.1.2, 2001-09-01 (Download)

  • Fix a bug in nmb.NetBIOSSession which specifies a TYPE_WORKSTATION for remote host instead of TYPE_SERVER.
  • Minor change to nmb.NetBIOSSession constructor API.
  • Fix a bug in smbdu which raises OverflowError when printing long file size values.
  • Fix a bug in smbcp which does not handle the destination path correctly when the source file is copied to a different filename.

Version 0.1.1, 2001-08-25 (Download)

  • Change nmb's NetBIOS and NetBIOSSession class such that they raise a NetBIOSError with a tuple of ( err_msg, err_class, err_code )
  • Add a function strerror() in both smb and nmb to return human readable messages for error codes.
  • Fix a bug in smbcp which fails to print an error message and terminate when the remote source path is not found.
  • Add in another utility, smblistshare.

Version 0.1.0, 2001-08-20 (Download)

  • First public release