Install & Compatibility
Where this runs
tested against v0.2.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 43.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.000s · 44MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to establish an SFTP connection using `pysftp.Connection` with a context manager, upload a local file, download a remote file, and list the contents of the current remote directory. It highlights the importance of host key verification, showing a common (but insecure for production) method to disable it for testing purposes. Credentials are retrieved from environment variables for security.
import pysftp
import os
# It is highly recommended to NOT disable host key checking in production.
# For proper security, manage known_hosts or explicitly add server keys.
cnopts = pysftp.CnOpts()
# !!! In production, configure hostkeys properly. DO NOT SET TO NONE. !!!
# For demonstration, we disable it here for easier local testing.
cnopts.hostkeys = None
HOSTNAME = os.environ.get('SFTP_HOSTNAME', 'sftp.example.com')
USERNAME = os.environ.get('SFTP_USERNAME', 'user')
PASSWORD = os.environ.get('SFTP_PASSWORD', 'secret_password')
try:
with pysftp.Connection(host=HOSTNAME, username=USERNAME, password=PASSWORD, cnopts=cnopts) as sftp:
print(f"Connection successfully established with {HOSTNAME}!")
print(f"Current remote directory: {sftp.pwd}")
# Example: Upload a file
local_file = 'local_test_file.txt'
remote_path = f'/remote/{local_file}'
with open(local_file, 'w') as f:
f.write('Hello, SFTP World!')
sftp.put(local_file, remote_path)
print(f"Uploaded {local_file} to {remote_path}")
# Example: Download a file
downloaded_file = 'downloaded_test_file.txt'
sftp.get(remote_path, downloaded_file)
print(f"Downloaded {remote_path} to {downloaded_file}")
# Example: List remote directory
print(f"Files in remote directory {sftp.pwd}:")
for entry in sftp.listdir():
print(f"- {entry}")
except pysftp.ConnectionException as e:
print(f"SFTP connection failed: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
finally:
# Clean up local test file if it was created
if os.path.exists(local_file):
os.remove(local_file)
if os.path.exists(downloaded_file):
os.remove(downloaded_file)
Debug
Known issues
breakingPySFTP is incompatible with Paramiko versions 4.0.0 and newer. Paramiko 4.0.0 removed the `DSSKey` class, which `pysftp` directly imports, leading to an `ImportError` when `paramiko >= 4.0.0` is installed.fixPin your `paramiko` dependency to a version less than 4.0.0 (e.g., `paramiko < 4.0.0`). For new projects, consider migrating to `paramiko` directly or a more actively maintained SFTP library.
affects: All PySFTP versions (0.2.9 and earlier)
gotchaThe PySFTP project has been inactive since its last release in July 2016. This means it may contain unpatched security vulnerabilities from its underlying dependencies (Paramiko) or within PySFTP itself, and lacks support for modern SSH features (e.g., newer key types like Ed25519, ECDSA).fixEvaluate the security risks for your specific use case. For new development or applications requiring strong security, it is highly recommended to use `paramiko` directly or an actively maintained alternative SFTP client library.
affects: All PySFTP versions (0.2.9 and earlier)
gotchaDisabling host key checking by setting `cnopts.hostkeys = None` is often shown in examples for convenience but exposes your connection to Man-in-the-Middle (MITM) attacks. This is a severe security vulnerability for production environments.fixAlways implement proper host key verification. Load known hosts from a file (e.g., `cnopts.hostkeys.load('/path/to/known_hosts')`) or explicitly add server keys. Never disable host key checking in production. affects: All PySFTP versions (0.2.9 and earlier)
gotchaThe recursive file transfer methods (`pysftp.Connection.put_r()` and `pysftp.Connection.get_r()`) are reported to have issues and may not function correctly on Windows operating systems.fixOn Windows, consider implementing recursive transfers manually by iterating through directories with `pysftp.Connection.listdir()` and using individual `get()`/`put()` calls, or use `paramiko` directly for more robust control.
affects: All PySFTP versions (0.2.9 and earlier)
Upgrade
Version history
0.2.9latest on PyPI · released Jul 6, 2016
Audit
Dependencies
paramikorequiredCore SSH/SFTP functionality, required version >= 1.15.2 but < 4.0.0.
pycryptorequiredCryptographic primitives, likely a transitive dependency via older Paramiko versions.