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
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.7s · import 0.000s · 29MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Session
✓ import ssh
✗ from ssh import Session
This quickstart demonstrates how to establish an SSH connection, authenticate with a password (using environment variables for safety), execute a simple command, capture its output, and properly close the session. It also includes basic error handling for common SSH exceptions. Replace `SSH_HOST`, `SSH_USER`, and `SSH_PASSWORD` with your actual server details.
import ssh
import os
try:
# Initialize an SSH session
session = ssh.Session()
# Set connection options
session.options_set(ssh.SSH_OPTIONS_HOST, os.environ.get('SSH_HOST', 'localhost'))
session.options_set(ssh.SSH_OPTIONS_PORT, int(os.environ.get('SSH_PORT', 22)))
# Connect to the SSH server
session.connect()
print(f"Connected to {session.options_get(ssh.SSH_OPTIONS_HOST)}:{session.options_get_int(ssh.SSH_OPTIONS_PORT)}")
# Authenticate using password
username = os.environ.get('SSH_USER', 'guest')
password = os.environ.get('SSH_PASSWORD', 'guestpass') # DO NOT hardcode passwords in production
if session.userauth_password(username, password) != ssh.SSH_AUTH_SUCCESS:
raise ssh.AuthError("Authentication failed")
print(f"Authenticated as {username}")
# Open a channel for executing commands
channel = session.channel_session()
channel.open_session()
# Execute a command
command = "echo Hello from ssh-python!"
print(f"Executing command: '{command}'")
channel.request_exec(command)
# Read output
stdout = channel.read_stdout(2048)
stderr = channel.read_stderr(2048)
exit_status = channel.get_exit_status()
print(f"--- STDOUT ---\n{stdout.decode().strip()}")
print(f"--- STDERR ---\n{stderr.decode().strip()}")
print(f"Exit Status: {exit_status}")
# Close the channel and session
channel.close()
print("Channel closed.")
session.disconnect()
print("Session disconnected.")
except ssh.AuthError as e:
print(f"Authentication Error: {e}")
except ssh.SSHException as e:
print(f"SSH Connection Error: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingOlder Python versions (e.g., <3.8) are no longer officially supported by ssh-python versions >= 1.1.0. Running on unsupported versions may lead to build failures or runtime issues.fixEnsure your development and deployment environments use Python 3.8 or newer. Upgrade your Python installation if necessary.
affects: <1.1.0
gotchaAlthough official wheels embed `libssh`, source installations (e.g., via `pip install --no-binary :all: ssh-python` or on unsupported platforms) require `libssh` development packages to be present on the system. This typically means `libssh-dev` (Debian/Ubuntu) or `libssh-devel` (RHEL/Fedora).fixFor source builds, install the appropriate `libssh` development package for your operating system. For most users, using pre-built wheels (`pip install ssh-python`) will avoid this dependency.
affects: All versions (for source builds)
breakingAPI features such as `channel.get_exit_status()` were introduced in `ssh-python` version 1.2.0. Attempting to use these features on older versions will result in an `AttributeError`.fixUpgrade to `ssh-python` 1.2.0 or newer to access the latest features and methods. Use `pip install --upgrade ssh-python`.
affects: <1.2.0
gotchaAuthentication failures are common due to incorrect credentials, invalid private key paths/permissions, or server-side configuration issues. The `AuthError` exception should be specifically handled.fixDouble-check usernames, passwords, and private key file paths/permissions (`chmod 600 key.pem`). Ensure the SSH server allows the chosen authentication method for the user. Implement specific `try...except ssh.AuthError` blocks.
affects: All versions
Upgrade
Version history
1.2.0.post1latest on PyPI · released Oct 12, 2025
Audit
Dependencies
libsshrequiredCore C library wrapper. Wheels embed libssh, but source builds require system libssh development headers.