{"id":8744,"library":"types-pysftp","title":"Typing stubs for pysftp","description":"types-pysftp provides PEP 561 compliant type stubs for the pysftp library, a simple interface for SFTP operations based on paramiko. It allows type checkers to analyze code utilizing pysftp, improving code quality and catching potential errors during development. The current version is 0.2.17.20260408, with releases tied to the typeshed project's update cadence for pysftp==0.2.*.","status":"active","version":"0.2.17.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["sftp","ssh","file transfer","typing","stubs","paramiko"],"install":[{"cmd":"pip install types-pysftp","lang":"bash","label":"Install types-pysftp"},{"cmd":"pip install pysftp","lang":"bash","label":"Install pysftp (runtime dependency)"}],"dependencies":[{"reason":"types-pysftp provides type stubs for this runtime library.","package":"pysftp","optional":false},{"reason":"pysftp is built on top of paramiko, which is a required transitive dependency.","package":"paramiko","optional":false}],"imports":[{"note":"While 'from pysftp import Connection' works, 'import pysftp' is the more common and recommended import pattern shown in pysftp's official documentation and examples.","wrong":"from pysftp import Connection","symbol":"Connection","correct":"import pysftp\nconn = pysftp.Connection(...)"}],"quickstart":{"code":"import pysftp\nimport os\n\nhostname = os.environ.get('SFTP_HOSTNAME', 'your.sftp.host')\nusername = os.environ.get('SFTP_USERNAME', 'your_username')\npassword = os.environ.get('SFTP_PASSWORD', '')\nprivate_key_path = os.environ.get('SFTP_PRIVATE_KEY_PATH', None) # e.g., '~/.ssh/id_rsa'\n\n# Recommended: configure known hosts for security\n# For testing, host key checking can be disabled (NOT RECOMMENDED for production)\ncnopts = pysftp.CnOpts()\ncnopts.hostkeys = None # Disable host key checking for demonstration only\n\ntry:\n    with pysftp.Connection(\n        hostname, \n        username=username,\n        password=password if not private_key_path else None,\n        private_key=private_key_path,\n        cnopts=cnopts\n    ) as sftp:\n        print(f\"Connection successfully established with {hostname}.\")\n        # Example: List contents of the remote directory\n        remote_path = '/'\n        print(f\"Listing contents of {remote_path}:\")\n        for entry in sftp.listdir(remote_path):\n            print(f\"- {entry}\")\n\n        # Example: Upload a file (create a dummy file first)\n        local_file = 'test_upload.txt'\n        with open(local_file, 'w') as f:\n            f.write('Hello from types-pysftp!')\n        remote_upload_path = f\"/remote_{local_file}\"\n        sftp.put(local_file, remote_upload_path)\n        print(f\"Uploaded {local_file} to {remote_upload_path}.\")\n        os.remove(local_file)\n\n        # Example: Download a file\n        local_download_path = 'downloaded_file.txt'\n        sftp.get(remote_upload_path, local_download_path)\n        print(f\"Downloaded {remote_upload_path} to {local_download_path}.\")\n        os.remove(local_download_path)\n\nexcept pysftp.ConnectionException as e:\n    print(f\"SFTP Connection Error: {e}.\")\n    print(\"Ensure hostname, username, password/private key are correct and host keys are properly handled.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Pin `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.","message":"`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`.","severity":"breaking","affected_versions":"pysftp==0.2.* with paramiko>=4.0.0"},{"fix":"For 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.","message":"By 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.","severity":"gotcha","affected_versions":"All versions of `pysftp` (and thus `types-pysftp` users)"},{"fix":"Consider 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.","message":"The `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.","severity":"deprecated","affected_versions":"pysftp==0.2.9 and earlier"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Downgrade `paramiko` to a version older than 4.0.0 (e.g., `pip install 'paramiko<4.0.0'`).","cause":"`pysftp` attempts to import `DSSKey` from `paramiko`, but this class was removed in `paramiko` version 4.0.0 and newer.","error":"ImportError: cannot import name 'DSSKey' from 'paramiko'"},{"fix":"Verify the hostname and port. Check firewall rules. Confirm your SFTP credentials are correct. Try connecting manually with a client like FileZilla to isolate the issue. If using a private key, ensure the path is correct and permissions are set appropriately.","cause":"This usually indicates a failure to connect to the SFTP server. Common causes include incorrect hostname, wrong port (default is 22), firewall blocking the connection, or invalid credentials (username/password/private key).","error":"pysftp.exceptions.ConnectionException: ('your.sftp.host', 22)"},{"fix":"For production, ensure the server's fingerprint is correctly added to your `known_hosts` file. For testing/development, you can bypass this by explicitly disabling host key checking: `cnopts = pysftp.CnOpts(); cnopts.hostkeys = None`. Pass `cnopts` to your `pysftp.Connection` constructor.","cause":"pysftp cannot find or verify the host's key in your known_hosts file, which is a security measure to prevent man-in-the-middle attacks.","error":"UserWarning: Failed to load HostKeys from ~/.ssh/known_hosts. You will need to explicitly load HostKeys (cnopts.hostkeys.load(filename)) or disable HostKey checking (cnopts.hostkeys = None)."}]}