{"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":"en","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"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}