{"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":"python","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":[{"wrong":"from pysftp-stubs import Connection","symbol":"Connection","correct":"from pysftp_stubs import 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,"search_vec":"'0.2':62 '0.2.17.20260408':49 '561':10 'allow':28 'analyz':32 'base':24 'cadenc':59 'catch':40 'checker':30 'code':33,37 'compliant':11 'current':46 'develop':44 'error':42 'file':65 'improv':36 'interfac':20 'librari':17 'oper':23 'paramiko':26,69 'pep':9 'potenti':41 'project':56 'provid':8 'pysftp':4,7,16,35,61 'qualiti':38 'releas':51 'sftp':22,63 'simpl':19 'ssh':64 'stub':2,13,68 'tie':52 'transfer':66 'type':1,6,12,29,67 'types-pysftp':5 'typesh':55 'updat':58 'util':34 'version':47","created_at":"2026-04-16T17:03:46.333843+00:00","updated_at":"2026-04-16T17:03:46.333843+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nModuleNotFoundError: No module named 'pysftp_stubs'"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.2.17.20260613","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/typeshed-internal/stub_uploader","docs":null,"changelog":"https://github.com/typeshed-internal/stub_uploader/blob/main/data/changelogs/pysftp.md","pypi":"https://pypi.org/project/types-pysftp/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}