Paramiko — SSH Protocol Implementation for Python

Introduction

Paramiko is the foundation of SSH automation in Python. It implements the SSHv2 protocol entirely in Python using cryptography primitives, making it portable across platforms. Tools like Fabric, Ansible, and sshuttle depend on Paramiko for their SSH transport layer.

What Paramiko Does

• Establishes SSH connections with password, public key, or agent-based authentication
• Executes remote commands and captures stdout, stderr, and exit status
• Transfers files via SFTP with put, get, and directory operations
• Creates SSH tunnels for local and remote port forwarding
• Implements both SSH client and server roles in pure Python

Architecture Overview

Paramiko models the SSH protocol as a Transport (encrypted channel), on top of which you open Channels for shell sessions, command execution, or SFTP subsystems. The Transport handles key exchange, encryption (AES, ChaCha20), and MAC verification. An SSHClient class wraps common operations (connect, exec_command, open_sftp) for convenience.

Self-Hosting & Configuration

• Install via pip: pip install paramiko
• Depends on the cryptography library for all crypto operations
• Load host keys from ~/.ssh/known_hosts or set a custom policy for verification
• Use SSH agent forwarding by connecting to the system SSH agent via paramiko.Agent
• Configure connection timeouts, banner timeouts, and keepalive intervals on the Transport

Key Features

• Pure Python: runs on any platform without compiled SSH binaries
• Full SFTP client with file read/write, directory listing, stat, chmod, and rename
• SSH tunnel support for both local-to-remote and remote-to-local port forwarding
• Ed25519, RSA, ECDSA, and DSA key support for authentication
• Gateway/jump host support for connecting through bastion servers via ProxyCommand

Comparison with Similar Tools

• Fabric — high-level SSH task runner built on top of Paramiko; Paramiko is the lower-level transport
• asyncssh — async SSH library for asyncio; Paramiko is synchronous but more widely deployed
• subprocess + ssh — shells out to the ssh binary; Paramiko keeps everything in-process with Python objects
• libssh2 (via pylibssh2) — C-based SSH; Paramiko is pure Python and easier to install but slower for bulk transfers

FAQ

Q: Is Paramiko secure for production use? A: Yes. It uses the well-audited cryptography library for all crypto operations and supports modern algorithms like Ed25519 and ChaCha20-Poly1305.

Q: How do I use SSH keys instead of passwords? A: Pass key_filename to connect(), or load keys from an SSH agent. Paramiko supports PEM, OpenSSH, and PKCS8 key formats.

Q: Can Paramiko transfer entire directories? A: The SFTP client operates on individual files. For directory transfers, walk the remote directory tree with listdir_attr and transfer files individually, or use a higher-level tool like Fabric.

Q: Does Paramiko support connection pooling? A: Not built-in. Open multiple channels on a single Transport for multiplexed operations over one TCP connection, which is more efficient than multiple connections.

Sources

• https://github.com/paramiko/paramiko
• https://www.paramiko.org