Registry / http-networking / ssh2-python

ssh2-python

JSON →
library1.2.0.post1pypypi✓ verified 84d ago

ssh2-python provides Python bindings for the `libssh2` C library, offering a low-level, high-performance interface for SSHv2 protocol operations. It is currently at version 1.2.0.post1 and is actively maintained with regular releases that include updates to embedded libraries like `libssh2` and OpenSSL, and support for newer Python versions.

pip install ssh2-python
INSTALL
IMPORT
SIG · SSH2-PYTHON
S
ssh2-python
http-networkingpythonv1.2.0.post1
Install
1.8s avg
Import
12ms
Disk
31MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.2.0.post1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.8s · import 0.012s · 33MB
31MB installed
● package 31MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Session
from ssh2.session import Session
SFTPHandle
from ssh2.sftp_handle import SFTPHandle
Channel
from ssh2.channel import Channel
exceptions
from ssh2 import exceptions

This quickstart demonstrates how to establish an SSH connection, authenticate with a username and password, execute a remote command, read its output, and gracefully close the connection. Ensure `SSH_HOST`, `SSH_PORT`, `SSH_USERNAME`, and `SSH_PASSWORD` environment variables are set for actual use.

import socket import os from ssh2.session import Session HOST = os.environ.get('SSH_HOST', 'localhost') PORT = int(os.environ.get('SSH_PORT', '22')) USERNAME = os.environ.get('SSH_USERNAME', 'user') PASSWORD = os.environ.get('SSH_PASSWORD', 'password') try: # 1. Create a socket and connect sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) sock.connect((HOST, PORT)) # 2. Initialize an SSH2 session session = Session() session.handshake(sock) # 3. Authenticate with password session.userauth_password(USERNAME, PASSWORD) # 4. Check if authenticated if not session.is_userauth_authenticated(): print("Authentication failed!") exit(1) print(f"Successfully authenticated to {HOST} as {USERNAME}") # 5. Open a channel and execute a command channel = session.open_session() channel.execute('echo Hello from ssh2-python; uname -a') # 6. Read output size, data = channel.read() while size > 0: print(data.decode('utf-8').strip()) size, data = channel.read() # 7. Get exit status print(f"Command exit status: {channel.get_exit_status()}") # 8. Close the channel and session channel.close() session.disconnect() sock.close() except exceptions.SSH2Error as e: print(f"SSH2 Error: {e}") except socket.error as e: print(f"Socket Error: {e}") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaThe underlying `libssh2` library does not support sharing sessions across multiple threads. While `ssh2-python` itself is thread-safe, each thread should have its own `Session` object to avoid issues.
fix
Ensure each thread initializes and manages its own `ssh2.session.Session` object.
affects: All versions
breakingIn version 1.2.0, several deprecated `libssh2` functions were removed from `ssh2.channel.Channel` and `ssh2.session.Session`. These include `receive_window_adjust`, `handle_extended_data`, `ignore_extended_data`, `startup`, `scp_recv`, and `scp_send`.
fix
Update code to use modern alternatives; for SCP, use `scp_recv2` and `scp_send64` if available, or higher-level libraries like `parallel-ssh` for file transfers.
affects: >=1.2.0
gotchaWhen installing `ssh2-python` from source, users often encounter build failures due to missing `libssh2` and `OpenSSL` development headers or `cmake`. Binary wheels provided via pip usually embed these dependencies.
fix
For source installs, ensure `libssh2-dev` (or equivalent) and `libssl-dev` (or equivalent OpenSSL development package) are installed on your system, along with `cmake`.
affects: All versions (source builds)
gotchaCalling `ssh2.session.Session.methods()` without a valid SSH connection could lead to a segmentation fault in versions prior to 1.1.1.
fix
Upgrade to version 1.1.1 or later. Always ensure a successful `session.handshake()` before calling `session.methods()`.
affects: <1.1.1
gotcha`ssh2-python` is a low-level binding to the `libssh2` C API. For most common SSH client tasks, a higher-level library like `parallel-ssh` (which uses `ssh2-python` internally) is recommended for ease of use and reduced boilerplate.
fix
Consider using `pip install parallel-ssh` if high-level abstractions for SSH operations are preferred over direct `libssh2` interaction.
affects: All versions
Errors
Common errors & fixes
Could NOT find OpenSSL, try to set the path to OpenSSL root folder in the system variable OPENSSL_ROOT_DIR (missing: OPENSSL_INCLUDE_DIR)
The `ssh2-python` build process (via `cmake` for `libssh2`) cannot locate the OpenSSL development libraries on your system, typically when installing from a source distribution without pre-compiled wheels.
fix
On Debian/Ubuntu: `sudo apt-get install libssl-dev`. On RedHat/CentOS: `sudo yum install openssl-devel`. Ensure `cmake` is also installed. Alternatively, ensure your `pip` is up-to-date and try installing again to get a binary wheel: `pip install -U pip && pip install ssh2-python`.
ERROR: Failed building wheel for ssh2-python` or `Command 'cmake ...' returned non-zero exit status 1.
Installation from source failed, often due to missing `libssh2` development libraries, `OpenSSL` development libraries, or `cmake`.
fix
Install `cmake` and the development packages for `libssh2` and `OpenSSL` on your system. For example, on Ubuntu: `sudo apt-get install cmake libssh2-1-dev libssl-dev`. If a binary wheel is available for your platform and Python version, upgrading `pip` might resolve it by allowing the installation of the wheel: `pip install -U pip`.
ssh2.exceptions.AuthenticationError: Publickey authentication failed
The provided public key or private key path is incorrect, the key is not authorized on the remote server, or the passphrase for the private key is wrong.
fix
Verify the paths to your public and private keys, ensure the public key is added to `~/.ssh/authorized_keys` on the remote server, and provide the correct passphrase if your private key is encrypted. Check `session.userauth_list()` to see available authentication methods on the server.
ssh2.exceptions.SocketRecvError: Error reading SSH protocol banner
The remote host did not respond with a valid SSH protocol banner, or the connection dropped before the banner could be read. This can indicate that the target port is not an SSH server, a firewall issue, or an unresponsive server.
fix
Verify the IP address and port are correct for your SSH server. Check firewall rules on both the client and server. Ensure the remote SSH server is running and accessible.
Upgrade
Version history
1.2.0.post1latest on PyPI · released Oct 12, 2025
Audit
Dependencies
libssh2optionalC library binding. Embedded in binary wheels but required for source builds.
OpenSSLoptionalRequired for cryptographic operations. Embedded in binary wheels but development libraries needed for source builds.
cmakeoptionalRequired for building from source, particularly for libssh2.
Agent activity
20 hits · last 30 days
node
16
OpenAI (training)
2
Resources
ssh2-python — pip install ssh2-python · libregistry