You can contribute to the project in a number of ways. Code is always good, bugs are interesting but tests make your famous!

Bug reports or feature enhancements that include a test are given preferential treatment. So instead of voting for an issue, write a test.


  1. Fork the repository on Bitbucket .
  2. Install supporting software packages and pysftp in –editable mode
    1. Make a virtualenv, clone the repos, install the deps from pip install -r requirements-dev.txt
    2. Install pysftp in editable mode, pip install -e .
  3. Write any new tests needed and ensure existing tests continue to pass without modification.
  1. Setup CI testing on for your Fork. See current script .
  2. As of verion 0.2.9, no tests are run against a public SFTP server. Keeping a server available was/is problematic and made for brittle testing. Becuase of this, we now use the pytest-sftpserver plugin for many tests. Testing features the concern authentication or authorization, i.e. different login types, chmod, chown have to be run against a local sshd and not the plugin as it does NOT support these types of tests.
  3. You will need to setup an ssh daemon on your local machine and create a user: test with password of test1357 – Tests that can only be run locally are skipped using the @skip_if_ci decorator so they don’t fail when the test suite is run on the CI server.
  1. Ensure that your name is added to the end of the Authors file using the format Name <> (url), where the (url) portion is optional.
  2. Submit a Pull Request to the project on Bitbucket.


We use sphinx to build the docs. make html is your friend, see docstrings for details on params, etc.

Bug Reports

If you encounter a bug or some surprising behavior, please file an issue on our tracker

Issue Priorities

This section lists the priority that will be assigned to an issue.

  1. Developer Issues
  2. Issues that have a pull request with a test(s) displaying the issue and code change(s) that satisfies the test suite
  3. Issues that have a pull request with a test(s) displaying the issue
  4. Naked pull requests - a code change request with no accompaning test
  5. An issue without a pull request with a test displaying the issue
  6. badly documented issue with no code or test - pysftp is not an end-user tool, it is a developer tool and it is expected that issues will be submitted like a developer and not an end-user. Issues in the realm of “the internet is broke” will be marked as invalid with a comment pointing the submitter to this section.


Tests specific to an issue should be put in the tests/ directory and the module should be named The tests within that module should be named test_issue_xx or test_issue_xx_YYYYYY if more than one test. Pull requests should not modify existing tests. See tests/ for a template and further explanation.