Paramiko

Paramiko is a pure-Python implementation of the SSHv2 protocol, providing both client and server functionality for secure remote command execution, interactive shells, and SFTP file transfer. It underpins higher-level tools like Fabric and is the SSH engine inside many DevOps and infrastructure-automation projects.

Because it’s written entirely in Python, with cryptographic primitives delegated to the cryptography and PyNaCl libraries, Paramiko runs anywhere CPython does without requiring an OpenSSH binary on the host. It exposes low-level primitives, transports, channels, key types, key exchange algorithms, for teams that need fine control, while SSHClient offers a batteries-included high-level API for the common case of connecting and running commands.

What You Get

• A high-level SSHClient for connecting, authenticating, and running remote commands in a few lines
• SFTP client and server implementations for programmatic file transfer
• Key generation, loading, and agent support for RSA, DSA, ECDSA, and Ed25519 keys
• Low-level Transport and Channel primitives for building custom SSH-based protocols
• An in-Python ServerInterface for implementing your own SSH or SFTP server

Common Use Cases

• Automating remote command execution across a fleet of Linux servers
• Building deployment and provisioning scripts that need SSH without invoking a subprocess
• Transferring files to and from remote hosts programmatically via SFTP
• Embedding an SSH server inside a Python application for remote administration

Under The Hood

Architecture

Paramiko is organized around a layered SSH2 stack: Transport (transport.py, 3,300+ lines) owns the socket, runs the packet read/write loop in its own thread, negotiates key exchange (kex_curve25519.py, kex_ecdh_nist.py, kex_gex.py, kex_group14/16.py), and multiplexes Channel objects (channel.py) over a single encrypted connection. AuthHandler/AuthStrategy (auth_handler.py, auth_strategy.py) handle the userauth phase against password, public-key, or keyboard-interactive methods. On top of this, SSHClient (client.py) is a facade that wires host-key policy (RejectPolicy/AutoAddPolicy), Transport construction, and Channel exec into a few high-level methods (connect, exec_command). SFTP is a parallel subsystem (sftp.py, sftp_client.py, sftp_server.py, sftp_handle.py) implemented as a request/response protocol running inside a dedicated SSH channel, independent of the shell/exec channel path. Key material (pkey.py, rsakey.py, ecdsakey.py, ed25519key.py) is abstracted behind a common PKey interface so Transport and SSHClient can treat all key types uniformly.

Tech Stack

Paramiko 5.0.0 targets Python >=3.9 and depends on cryptography>=3.3 for AES/RSA/ECDSA primitives (via cryptography.hazmat), bcrypt>=3.2 for key derivation, pynacl>=1.5 for Ed25519/Curve25519, and invoke>=2.0 for its own task runner. It has zero pure-Python crypto: all cipher/kex/hash operations go through cryptography’s Rust/C bindings, which is also why the project ships precompiled wheels rather than vendoring crypto code. Dev tooling (pyproject.toml dependency-groups) uses pytest-relaxed, flake8, a pinned black==22.12.0, codespell, and coverage, a traditional if slightly dated Python toolchain. Distribution is a single paramiko package with no compiled extensions of its own.

Code Quality

The test suite (24 files under tests/) is substantial: test_client.py alone defines 35+ test functions covering SSHClient connection, auth failure paths, host-key policies, and banner timeouts, using a real in-process NullServer/ServerInterface pair over a loopback socket rather than mocks, which gives good protocol-level coverage. Tests use pytest with pytest-relaxed and include fixture key files for every supported key type (RSA/DSA/ECDSA/Ed25519, with and without passwords). Code style is enforced via flake8 plus pinned black, and modules consistently raise explicit ssh_exception.py types (AuthenticationException, SSHException, NoValidConnectionsError) rather than bare exceptions. The codebase is old (started 2009) and shows it in places, repeated GPL-style file headers, no type hints, but naming and module boundaries stay disciplined.

API Design

The two-tier API is Paramiko’s main developer-experience win: SSHClient covers the common case (connect() plus exec_command() in a few lines, with context-manager support via ClosingContextManager), while Transport/Channel are exposed directly for anyone needing raw control over kex algorithms, window sizes, or custom channel types. Docstrings are present on nearly every public method and versioned with .. versionadded:: markers, and the README explicitly steers common use-cases toward Fabric instead of raw Paramiko, which is an honest signal about where the low-level API adds friction. The main cost for newcomers is that a working connection requires understanding host-key verification policy up front, since RejectPolicy is the secure default and will silently reject unknown hosts until a policy is set, a real first-run stumbling block the docs address but don’t eliminate.