Install & Compatibility
Where this runs
tested against v1.4.0 · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.8s · import 0.053s · 26MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Session
✓ from pylibsshext.session import Session
✗ from ansible_pylibssh.session import Session
Core classes are exposed via the `pylibsshext` module, not directly from `ansible_pylibssh`.
LibsshSessionException
✓ from pylibsshext.errors import LibsshSessionException
✗ from ansible_pylibssh.errors import LibsshSessionException
Exceptions are located in the `pylibsshext.errors` submodule.
__version__
✓ from pylibsshext import __version__
Library version information and other global attributes are available directly from `pylibsshext`.
This quickstart demonstrates how to establish an SSH session, execute a simple command, and then properly disconnect. It uses environment variables for host, user, and password for security and flexibility. Ensure the `libssh` C library is installed on your system and replace `SSH_HOST` and `SSH_USER` with valid credentials if not using a passwordless setup.
import os
from pylibsshext.errors import LibsshSessionException
from pylibsshext.session import Session
HOST = os.environ.get('SSH_HOST', 'localhost')
USER = os.environ.get('SSH_USER', 'testuser')
PASSWORD = os.environ.get('SSH_PASSWORD', '')
# Use a placeholder if not set, but real connections need a password or key
if not PASSWORD:
print("Warning: SSH_PASSWORD environment variable not set. Connection might fail if password authentication is required.")
TIMEOUT = 30
PORT = 22
ssh = Session()
try:
ssh.connect(
host=HOST,
user=USER,
password=PASSWORD,
timeout=TIMEOUT,
port=PORT,
)
print(f'Successfully connected to {HOST}:{PORT}.')
# Example: Execute a command
channel = ssh.open_session()
channel.request_exec('echo Hello from pylibssh!')
output = channel.read_stdout(2048).decode()
print(f'Command output: {output.strip()}')
channel.close()
channel.send_eof()
except LibsshSessionException as ssh_exc:
print(f'Failed to connect to {HOST}:{PORT} over SSH: {ssh_exc!s}')
except Exception as e:
print(f'An unexpected error occurred: {e}')
finally:
if ssh.is_connected:
ssh.disconnect()
print(f'Disconnected from {HOST}.')
Debug
Known issues
gotchaThe library is a set of Python bindings for `libssh`. Therefore, `libssh` (version 0.9.0 or newer) must be installed at the system level for `ansible-pylibssh` to function. Installing the Python package via pip alone is insufficient.fixInstall `libssh` development packages (e.g., `libssh-dev` on Debian/Ubuntu, `libssh-devel` on RHEL/Fedora, or via Homebrew on macOS) matching version 0.9.0 or later on your operating system.
affects: All versions
breakingSupport for Python 3.6, 3.7, and 3.8 was dropped with version 1.4.0. Installations on these Python versions will fail or result in an incompatible state.fixUpgrade your Python environment to Python 3.9 or newer before installing `ansible-pylibssh` version 1.4.0 or later.
affects: 1.4.0 and later
gotchaOlder versions (prior to v1.2.2) had a bug where downloading files larger than 64kB over SCP could fail, leading to incomplete transfers.fixUpgrade `ansible-pylibssh` to version 1.2.2 or newer to ensure reliable SCP transfers for larger files.
affects: < 1.2.2
gotchaPrior to version 1.2.1, attempting to download a non-existent remote file via SCP could lead to program crashes.fixUpgrade `ansible-pylibssh` to version 1.2.1 or newer to prevent crashes when handling non-existent remote files during SCP operations.
affects: < 1.2.1
gotchaEarlier versions (prior to v1.2.0) could crash if `channel.recv` was called and `libssh` returned an `SSH_EOF` error, or if a channel was not explicitly closed.fixUpgrade `ansible-pylibssh` to version 1.2.0 or newer for improved stability and crash prevention related to channel handling.
affects: < 1.2.0
breakingAs of version 1.4.0, macOS wheels require macOS version 15.0 or newer due to updates in the `cibuildwheel` process. Installations on older macOS versions may encounter issues.fixEnsure your macOS environment is version 15.0 or newer when installing `ansible-pylibssh` 1.4.0+ to use pre-compiled wheels. Alternatively, attempt to build from source (which may require specific build tools and `libssh` installation).
affects: 1.4.0 and later on macOS
Errors
Common errors & fixes
[WARNING]: ansible-pylibssh not installed, falling back to paramiko
Ansible defaults to using the 'paramiko' SSH library because 'ansible-pylibssh' is not installed.
fixInstall 'ansible-pylibssh' using pip: 'pip install ansible-pylibssh'.
fatal: [10.96.192.10]: FAILED! => {"changed": false, "msg": "paramiko: The authenticity of host '10.96.192.10' can't be established.\nThe ssh-ed25519 key fingerprint is b'REDACTED'."}
The SSH client cannot verify the host's identity because the host key is not in the known_hosts file.
fixManually add the host key to the known_hosts file or configure Ansible to accept unknown host keys.
ld: library not found for -lssh
The linker cannot find the 'libssh' library during the installation of 'ansible-pylibssh'.
fixEnsure 'libssh' is installed on your system. On macOS, you can install it using Homebrew: 'brew install libssh'.
fatal: [10.2.201.194]: FAILED! => {"changed": false, "msg": "paramiko is not installed: No module named 'paramiko'"}
Ansible falls back to 'paramiko' for SSH connections, but 'paramiko' is not installed.
fixInstall 'paramiko' using pip: 'pip install paramiko'.
fatal error: 'libssh/libssh.h' file not found
ansible-pylibssh requires the `libssh` client library and its development headers (version 0.9.0 or newer) to be present and discoverable by the compiler during installation, which can be challenging on macOS or when building from source without proper CFLAGS.
fixInstall `libssh` using your system's package manager (e.g., `brew install libssh` on macOS, `sudo apt-get install libssh-dev` on Debian/Ubuntu, `sudo dnf install libssh-devel` on RHEL/Fedora) and then install `ansible-pylibssh` using `pip` with appropriate CFLAGS if necessary, especially on macOS. For macOS with Homebrew, use: `CFLAGS="-I $(brew --prefix)/include -I ext -L $(brew --prefix)/lib -lssh" pip install ansible-pylibssh`
Upgrade
Version history
1.4.0latest on PyPI · released Mar 16, 2026
Audit
Dependencies
libsshrequiredRequires the system-level libssh C library (version 0.9.0 or newer) to be installed for the Python bindings to function. This is a crucial runtime dependency, not a Python package.