{"id":1141,"library":"types-paramiko","title":"Typing Stubs for Paramiko","description":"types-paramiko provides static type checking stubs for the Paramiko SSH library. It allows type checkers like Mypy and Pyright to analyze code that uses `paramiko` for better IDE support, type inference, and catching type-related errors before runtime. This package is part of the Typeshed project, aims to provide accurate annotations for `paramiko==4.0.*`, and is updated frequently, sometimes daily.","status":"active","version":"4.0.0.20260402","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","paramiko","ssh","type-checking"],"install":[{"cmd":"pip install types-paramiko paramiko","lang":"bash","label":"Install types-paramiko and Paramiko"}],"dependencies":[{"reason":"This package provides typing stubs for `paramiko`, so `paramiko` itself is a mandatory runtime dependency for your project.","package":"paramiko","optional":false},{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"symbol":"SSHClient","correct":"import paramiko\nclient = paramiko.SSHClient()"},{"symbol":"Transport","correct":"import paramiko\ntransport = paramiko.Transport(...)"},{"symbol":"PKey","correct":"import paramiko\nkey = paramiko.PKey()"}],"quickstart":{"code":"import paramiko\nimport os\nimport sys\n\ndef ssh_connect_and_execute(\n    hostname: str,\n    username: str,\n    command: str,\n    password: str = None,\n    port: int = 22\n) -> str:\n    client = paramiko.SSHClient()\n    # Automatically add new host keys (use with caution in production)\n    client.set_missing_host_key_policy(paramiko.AutoAddPolicy())\n    \n    try:\n        # Load system host keys by default\n        client.load_system_host_keys()\n        \n        if password:\n            client.connect(hostname, port=port, username=username, password=password, timeout=10)\n        else:\n            # Assumes an SSH agent is running or keys are in default locations\n            client.connect(hostname, port=port, username=username, timeout=10)\n\n        # Execute a command\n        stdin, stdout, stderr = client.exec_command(command)\n        output = stdout.read().decode().strip()\n        error = stderr.read().decode().strip()\n        \n        if error:\n            print(f\"Error executing command: {error}\", file=sys.stderr)\n            return \"\"\n        return output\n    except paramiko.AuthenticationException:\n        print(\"Authentication failed, please verify your credentials (username/password/keys).\", file=sys.stderr)\n        return \"\"\n    except paramiko.SSHException as e:\n        print(f\"SSH connection or command execution failed: {e}\", file=sys.stderr)\n        return \"\"\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\", file=sys.stderr)\n        return \"\"\n    finally:\n        # Always close the client connection to prevent resource leaks\n        if client:\n            client.close()\n\nif __name__ == \"__main__\":\n    # Example usage with environment variables\n    HOST = os.environ.get(\"SSH_HOST\", \"your_ssh_server.com\")\n    USER = os.environ.get(\"SSH_USER\", \"your_username\")\n    PASS = os.environ.get(\"SSH_PASSWORD\", \"\") # Use SSH keys whenever possible\n    CMD = os.environ.get(\"SSH_COMMAND\", \"echo Hello from Paramiko!\")\n    PORT = int(os.environ.get(\"SSH_PORT\", 22))\n\n    if HOST == \"your_ssh_server.com\":\n        print(\"Please set SSH_HOST, SSH_USER, and optionally SSH_PASSWORD/SSH_PORT environment variables.\", file=sys.stderr)\n        sys.exit(1)\n\n    print(f\"Attempting to connect to {USER}@{HOST}:{PORT} and execute '{CMD}'\")\n    result = ssh_connect_and_execute(HOST, USER, CMD, PASS if PASS else None, PORT)\n    if result:\n        print(\"\\n--- Command Output ---\")\n        print(result)\n    else:\n        print(\"\\n--- Command execution failed ---\", file=sys.stderr)","lang":"python","description":"This quickstart demonstrates a basic SSH connection and command execution using Paramiko. With `types-paramiko` installed, a type checker can provide static analysis for the Paramiko calls and type hints in this code."},"warnings":[{"fix":"Ensure that your `paramiko` version aligns with the version targeted by `types-paramiko`. Check the `types-paramiko` PyPI page for the supported `paramiko` range. Consider pinning both `paramiko` and `types-paramiko` versions in your `requirements.txt` (e.g., `paramiko==4.0.0` and `types-paramiko==4.0.0.YYYYMMDD`).","message":"The `types-paramiko` package is designed to provide accurate type annotations for a specific major version of `paramiko` (e.g., `paramiko==4.0.*`). Using it with significantly older or newer `paramiko` versions may lead to incorrect type checking results or errors.","severity":"gotcha","affected_versions":"paramiko versions incompatible with types-paramiko 4.x"},{"fix":"Regularly update `types-paramiko`. If encountering issues, check the Typeshed GitHub repository for recent changes or open an issue if the stubs are significantly out of date. Consider temporarily suppressing specific type checking errors if a new `paramiko` feature is used but not yet stubbed.","message":"Type stubs, especially for third-party libraries, can sometimes lag behind the runtime package. New features or API changes in `paramiko` might not immediately have corresponding type annotations in `types-paramiko`, leading to `mypy` or `pyright` reporting errors or missing type information.","severity":"gotcha","affected_versions":"All versions, as it's an inherent aspect of separate stub packages"},{"fix":"Always ensure `client.close()` is called, preferably within a `finally` block, after you are done with the SSH client or other Paramiko connection objects.","message":"It is crucial to explicitly call `.close()` on `paramiko.SSHClient` and other connection objects when you are finished with them. Failing to do so can lead to resource leaks, hanging processes, or unexpected behavior at application shutdown, particularly in long-running applications or scripts.","severity":"gotcha","affected_versions":"All Paramiko versions"},{"fix":"Test thoroughly against your target SSH server. If issues occur with non-standard implementations, consider contributing a patch to the `paramiko` project or using an alternative library specifically designed for that environment (e.g., `netmiko` for network devices).","message":"Paramiko is primarily designed to work with standard OpenSSH implementations. While it can connect to various SSH servers, issues might arise with non-Unix-like or proprietary SSH implementations (e.g., some Cisco devices, Windows SSH servers). These issues might not be prioritized for fixes unless a community-contributed patch is provided.","severity":"gotcha","affected_versions":"All Paramiko versions"},{"fix":"For complex interactive SSH sessions, consider using `paramiko.Channel` directly with `recv()` and `send()` methods, along with careful prompt parsing. Alternatively, for network device automation, higher-level libraries like `Netmiko` (which builds upon Paramiko) are specifically designed to handle interactive CLI sessions robustly.","message":"Directly using `paramiko.SSHClient.exec_command()` for sequences of interactive commands or where output parsing depends on specific prompts can be unreliable. `exec_command` is best for single, non-interactive commands. Handling complex, interactive sessions requires managing input/output streams and parsing prompts manually, which is prone to race conditions and unreliability.","severity":"gotcha","affected_versions":"All Paramiko versions"},{"fix":"Ensure that SSH connection parameters such as `hostname`, `username`, `password`, or `key_filename` are correctly provided to `paramiko.SSHClient.connect()` or similar methods. For scripts or tests, these can be passed via environment variables (as suggested by the test output), configuration files, or directly in the code.","message":"Paramiko requires SSH connection parameters (e.g., host, username, password or private key) to be supplied to establish a connection. If these are not provided, connection attempts will fail, and the library will not be able to perform its intended functions.","severity":"gotcha","affected_versions":"All Paramiko versions"}],"env_vars":null,"search_vec":"'4.0':61 'accur':57 'aim':54 'allow':19 'analyz':27 'annot':58 'better':33 'catch':39 'check':11,74 'checker':21 'code':28 'daili':67 'error':43 'frequent':65 'ide':34 'infer':37 'librari':17 'like':22 'mypi':23 'packag':47 'paramiko':4,7,15,31,60,70 'part':49 'project':53 'provid':8,56 'pyright':25 'relat':42 'runtim':45 'sometim':66 'ssh':16,71 'static':9 'stub':2,12,69 'support':35 'type':1,6,10,20,36,41,68,73 'type-check':72 'type-rel':40 'types-paramiko':5 'typesh':52 'updat':64 'use':30","created_at":"2026-04-05T13:07:27.331819+00:00","updated_at":"2026-04-16T23:40:48.147514+00:00","problems":{"verify_error":"error: Failed to parse: `types-paramiko paramiko`\n  Caused by: Expected one of `@`, `(`, `<`, `=`, `>`, `~`, `!`, `;`, found `p`\ntypes-paramiko paramiko\n               ^"},"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"5.0.0.20260724","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/paramiko.md","pypi":"https://pypi.org/project/types-paramiko/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-05","install_tag":"verified"}}