A Software Technologist's Blog (Wanna Email Me?)


June 9, 2009 By miketeo

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.


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.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 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
  1. miketeo Said,

    @Peter Simm: As of pysmb 1.1.16, no. I will see if I can add this feature in the next release.

  2. bin.li Said,

    hello Mike,
    I’m trying to list all files in a remote shared dir with pysmb 1.1.15 & pysmb 1.1.17(use conn.listPath method). And it will raise smb.smb_structs.OperationFailure: Failed to list xxx on xx: Unable to retrieve file list for some of my directories (most directories works ok, but a few of them fails), what’s the problem??

  3. Sly Said,

    Awesome module. I just have one issue and perhaps you can help. Everything works perfectly when I connect to NAS, use listPath to see if certain files already exist or not and then move those files using storeFileOffSet. Yet for some reason when I immediately try doing the exact same process again I get an operationFailure/Unable to retrieve file list error. I’ve tried setting up a while loop that disconnects and reconnects but even that doesn’t work. Same error. Every time I want to run this code I have to close my app and reopen and then it works! The first time of course but then crashes the second. Any idea as to why this happens? Thanks.

  4. Innerink Said,

    I’m trying to study use pysmb to sync my samba server. When i used listPath,the result print just like “smb.base.SharedFile object at 0x00000000039458D0”. How can i translate it to the real path that i can use ?

  5. miketeo Said,

    @Innerink: The listPath returns a list of SharedFile instances. You can iterate through each SharedFile instance to perform further operations. You can find more information on the SharedFile class at https://pythonhosted.org/pysmb/api/smb_SharedFile.html

  6. Jav Said,

    Hi MIke,

    Been using this very sucessfully to mount and read CIFS file shares and files, my company is now starting to move to windows DFS, is there any support for DFS planned?

  7. miketeo Said,

    @Jav: Due to lack of time and equipment constraints, there are no plans to support DFS for pysmb yet.

  8. Julian Said,

    Hi Mike,

    Thanks for sharing your code. I’m using “SMBConnection.listPath” which is working great but just wanted to know what order the list get returned in? It seems like created date but not sure and is there any way to change the order?

    Also is there any where explaining a bit more about the “search” function in this class, as I cannot get it to work.


  9. miketeo Said,

    @Julian: The order of the results for listPath depends on the OS. pysmb didn’t provide a sorting order as the SMB specs didn’t really provide a concrete reference for such feature and it was thought that it would be easy to implement the sorting at client-end.

    I have other users reporting issues with the search function on OS X and with recent Windows versions. Please let me know what is the OS of your server. At this moment, I am too busy with my work and family to investigate further on this.

  10. Vojslav Said,


    after Samba update to 4.4 we cannot use pysmb (in ubuntu 14.04 lts) : conn.listShares() ends wir error message “Failed to list shares: Unable to connect to IPC$”. Window user can with Samba shares normaly work. Has anybody experiencies with this error? Thanks. Vojslav

  11. Vojslav Said,

    I think there are bug in pysm 1.18 – when on samba server in smb.conf
    is switch server signing = mandatory – psymb is not able to comunicate with samba server ( with server signing = auto it is ok)

    in log on samba server – bad signature message


  12. Dan Said,

    The documentation is down.

  13. admin Said,

    @Dan: Online documentation is now at http://pysmb.readthedocs.io/

  14. althonos Said,

    @Miketeo: Hi there, just a quick comment to inform you that I have been using pysmb as the base of https://github.com/althonos/fs.smbfs, an extension of the pyfilesystem2 library allowing access to an SMB server through the fs API.

  15. Jeff Said,

    When I try to open a file on a different subnet through a core router I get this error message: “Hostname does not reply back with its machine name”

    Is this expected behavior?

  16. miketeo Said,

    @Jeff, I think you are using the smb:// URLhandler. pysmb has not received the remote server’s machine name, so it is not able to proceed with the pysmb operation. Another way is to switch using SMBConnection.

    conn = SMBConnection(userID, password, client_machine_name, server_name, use_ntlm_v2 = True)
    assert conn.connect(server_ip, 139)
    file_obj = tempfile.NamedTemporaryFile()
    file_attributes, filesize = conn.retrieveFile('smbtest', '/rfc1001.txt', file_obj)

  17. MadInc Said,

    Hi. Great library. Please tell me how I can send the file from the local Windows directory to the smb Ubuntu server, I’m trying to do this:
    use SMBConnection

    with open(file, ‘rb’) as upload_file:
    smbcon.storeFile(remote_dir, ‘/’ + os.path.basename(file), upload_file)

    I see an error that can not connect:
    Unable to connect to shared device python smb

    I feel that the problem is in the server directory being set, i try:
    remote_dir = ‘//server_name/directory’
    remote_dir = ‘/server_name/directory’
    remote_dir = ‘\\server_name\directory’
    remote_dir = ‘\\\\server_name\\directory’

    How to set the destination folder correctly ?

  18. miketeo Said,

    @MadInc: I don’t think you have connected successfully to the remote drive yet.

    conn = SMBConnection(userID, password, 'MYMACHINE', 'MYSERVER')
    assert conn.connect(server_ip, 139)
    with open(file, ‘rb’) as upload_file:
      conn.storeFile('SHAREDFOLDER', '/folder1/file.dat', upload_file)
  19. Julian Said,

    pysmb support for SMBv3:
    Several services are moving from SMB2 to SMB3 and scripts using pysmb won’t be able to connect if the services does not support SMB2 anymore.

  20. Gray Said,

    Hi, Mike! I’ve found pysmb to be invaluable in a recent project. A few folks in my workplace are concerned about using pysmb in a production Python environment, though, because your readme describes it as ‘experimental’. Are those concerns justified? In what way would you say the library is experimental? Thanks so much!

  21. Srihari Said,

    Hi Mike,

    I’m was using the pysmb package for SMB share access. Due to security reasons, Admins set a minimum protocol version as 2.0 after which the connection to SMB share is not happening using SMBConnection. Need your help on this.

  22. Srihari Said,

    Hi Mike,

    After disabling SMB1 in SMB share, I’m not able to access the SMB share using SMBConnection. Need your help on this.

    Thanks 🙂

  23. miketeo Said,

    Recent releases of pysmb do support SMB 2.002 dialect.

  24. Srihari Said,

    Can i get the git hub link for the latest version please ? And is there any change in usage ?

  25. Srihari Said,

    Hi Mike,

    Found the below differences which I noticed, downloaded the latest package from pyCharm and the connection works smoothly. But when I try to download the package from github link : https://github.com/miketeo/pysmb I’m getting the below error :

    line 355, in decode
    message.raw_data, message)
    smb.smb_structs.ProtocolError: NT LAN Manager dialect selected in SMB_COM_NEGOTIATE but parameters bytes count (2) does not meet specs
    ==================== SMB Message ====================
    Command: 0x72 (SMB_COM_NEGOTIATE)
    Status: NTSTATUS=0x00000000
    Flags: 0x88
    Flags2: 0xC003
    PID: 81854
    UID: 0
    MID: 1
    TID: 0
    Security: 0x0000000000000000
    Parameters: 2 bytes
    Data: 0 bytes
    ==================== SMB Data Packet (hex) ====================

    Any help would be much appreciated.

    Thanks 🙂

  26. Srihari Said,

    I think I found the reason. The package downloaded in pycharm points to dev-2.0.x branch, where the connection to SMB works seamless regardless of whether SMB1 is disabled or enabled.
    But the master branch does not have these changes published yet. And still facing the above-mentioned error.

    Any plan of when these changes will be published?

  27. miketeo Said,

    There are no immediate plans to publish dev-2.0.x as it does not work reliably across some of the OS yet.

  28. SRIHARI K Said,

    Does this support IPv6 connection ?

  29. miketeo Said,


    conn = SMBConnection(userID, password, client_machine_name, server_name, use_ntlm_v2 = True)
    assert conn.connect(server_ip, 139, socket.AF_INET6)

Add A Comment