Install & Compatibility
Where this runs
tested against v0.2.17.20260613 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 99.7MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 3.1s · import 0.000s · 35MB
59MB installed
● package 59MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Connection
✓ from pysftp_stubs import Connection
✗ from pysftp-stubs import Connection
This quickstart demonstrates how to establish an SFTP connection using pysftp, list remote directory contents, upload a file, and download a file. It uses environment variables for credentials and explicitly disables host key checking for simplicity, though this is not recommended for production environments. The Connection object is used as a context manager to ensure the SFTP session is properly closed.
import pysftp
import os
hostname = os.environ.get('SFTP_HOSTNAME', 'your.sftp.host')
username = os.environ.get('SFTP_USERNAME', 'your_username')
password = os.environ.get('SFTP_PASSWORD', '')
private_key_path = os.environ.get('SFTP_PRIVATE_KEY_PATH', None) # e.g., '~/.ssh/id_rsa'
# Recommended: configure known hosts for security
# For testing, host key checking can be disabled (NOT RECOMMENDED for production)
cnopts = pysftp.CnOpts()
cnopts.hostkeys = None # Disable host key checking for demonstration only
try:
with pysftp.Connection(
hostname,
username=username,
password=password if not private_key_path else None,
private_key=private_key_path,
cnopts=cnopts
) as sftp:
print(f"Connection successfully established with {hostname}.")
# Example: List contents of the remote directory
remote_path = '/'
print(f"Listing contents of {remote_path}:")
for entry in sftp.listdir(remote_path):
print(f"- {entry}")
# Example: Upload a file (create a dummy file first)
local_file = 'test_upload.txt'
with open(local_file, 'w') as f:
f.write('Hello from types-pysftp!')
remote_upload_path = f"/remote_{local_file}"
sftp.put(local_file, remote_upload_path)
print(f"Uploaded {local_file} to {remote_upload_path}.")
os.remove(local_file)
# Example: Download a file
local_download_path = 'downloaded_file.txt'
sftp.get(remote_upload_path, local_download_path)
print(f"Downloaded {remote_upload_path} to {local_download_path}.")
os.remove(local_download_path)
except pysftp.ConnectionException as e:
print(f"SFTP Connection Error: {e}.")
print("Ensure hostname, username, password/private key are correct and host keys are properly handled.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breaking`pysftp` is incompatible with `paramiko` versions 4.0.0 and above. Attempting to use `pysftp` with `paramiko>=4.0.0` will result in an `ImportError` due to `DSSKey` being removed from `paramiko`.fixPin `paramiko` to `<4.0.0` in your project dependencies (e.g., `paramiko<4.0.0`). The `types-pysftp` package provides stubs for `pysftp==0.2.*`, which predates `paramiko`'s breaking change.
affects: pysftp==0.2.* with paramiko>=4.0.0
gotchaBy default, `pysftp` performs host key verification, which can lead to 'No hostkey for host X found' errors if the server's host key is not in `~/.ssh/known_hosts` or a specified `HostKeys` object.fixFor production, ensure the server's host key is properly added to your `known_hosts` file. For development or testing, you can disable host key checking by setting `cnopts = pysftp.CnOpts(); cnopts.hostkeys = None` and passing `cnopts` to `pysftp.Connection`. This is not recommended for production due to security implications.
affects: All versions of `pysftp` (and thus `types-pysftp` users)
deprecatedThe `pysftp` library itself appears to be largely unmaintained, with its last PyPI release (0.2.9) dating back to 2016. While `types-pysftp` (from typeshed) continues to be updated, the underlying `pysftp` library may not receive future bug fixes or security updates.fixConsider migrating to `paramiko` directly for more actively maintained SFTP functionality, especially for new projects or if advanced features/security updates are critical. `pysftp` is a wrapper around `paramiko` and `paramiko` is actively maintained.
affects: pysftp==0.2.9 and earlier
Upgrade
Version history
0.2.17.20260613latest on PyPI · released Jun 13, 2026
Audit
Dependencies
pysftprequiredtypes-pysftp provides type stubs for this runtime library.
paramikorequiredpysftp is built on top of paramiko, which is a required transitive dependency.