Registry / http-networking / asyncssh

asyncssh

JSON →
library2.24.0pypypi✓ verified 25d ago

AsyncSSH is an asynchronous Python library providing a client and server implementation of the SSHv2 protocol, built on top of the `asyncio` framework. It supports a wide range of features including shell, command, and subsystem channels, SFTP, SCP, port forwarding, and various authentication methods. The library is actively maintained, with a recent major version (2.x) and regular patch releases.

pip install asyncssh
INSTALL
IMPORT
SIG · ASYNCSSH
A
asyncssh
http-networkingpythonv2.24.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.24.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
musl
glibc
py 3.10
1/2 runs
1/2 runs
py 3.11
1/2 runs
1/2 runs
py 3.12
1/2 runs
1/2 runs
py 3.13
1/2 runs
1/2 runs
py 3.9
1/2 runs
1/2 runs
Code
Verified usage

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

asyncssh
import asyncssh
Primary library import.
asyncio
import asyncio
Required as AsyncSSH is built on asyncio.

This quickstart demonstrates how to establish an SSH client connection to a remote host, run a command, and print its output using `asyncssh.connect` and `conn.run`. It uses environment variables for host, port, username, and password for secure testing. For local testing, ensure an SSH server is running and configured correctly.

import asyncio import asyncssh import os async def run_client(): host = os.environ.get('SSH_HOST', 'localhost') port = int(os.environ.get('SSH_PORT', 22)) username = os.environ.get('SSH_USERNAME', 'testuser') password = os.environ.get('SSH_PASSWORD', '') # Or use client_keys=['/path/to/id_rsa'] try: # Connect to the SSH server conn = await asyncssh.connect(host, port=port, username=username, password=password) # Run a command and get the result result = await conn.run('echo "Hello from AsyncSSH!"', check=True) print(f"Command: {result.command}") print(f"Stdout: {result.stdout.strip()}") print(f"Stderr: {result.stderr.strip()}") print(f"Return code: {result.returncode}") # Close the connection (async with handles this implicitly if used for conn) conn.close() except (asyncssh.Error, OSError) as exc: print(f'SSH connection or command failed: {exc}') if __name__ == '__main__': # Note: For 'localhost' testing, you might need a local SSH server configured # to accept connections for the specified username/password or client_key. # Example to run: # SSH_HOST=your_ssh_server SSH_USERNAME=your_user SSH_PASSWORD=your_pass python your_script.py asyncio.run(run_client())
Debug
Known issues
breakingAsyncSSH 2.0 and later requires Python 3.10 or newer. Users on older Python 3 versions (e.g., 3.6-3.9) must use AsyncSSH 1.x or upgrade their Python interpreter.
fix
Upgrade Python to 3.10+ or pin AsyncSSH to a 1.x version compatible with your Python environment.
affects: >=2.0.0
breakingAsyncSSH 2.0+ mandates `cryptography` version 39.0 or higher. Upgrading `asyncssh` might require a concurrent upgrade of the `cryptography` dependency, which could have its own breaking changes if coming from a very old version.
fix
Ensure `cryptography>=39.0` is installed alongside `asyncssh`. Check `cryptography` release notes for its own breaking changes if updating from a significantly older version.
affects: >=2.0.0
breakingIn AsyncSSH 2.x, methods such as `asyncssh.create_server`, `asyncssh.listen`, `asyncssh.listen_reverse`, and `SSHClientConnection`'s server/forwarding methods now raise an exception (e.g., `asyncssh.ChannelListenError`) on listen failures, instead of returning `None`.
fix
Update error handling logic to catch the appropriate `asyncssh.Error` subclass (e.g., `ChannelListenError`) instead of checking for `None` return values.
affects: >=2.0.0
breakingStarting with AsyncSSH 2.19.0, the `SSHClientConfig.load` method (and potentially related config parsing logic) gained new `canonical` and `final` arguments. Code that directly calls this method or relies on its previous signature might break.
fix
Review calls to `SSHClientConfig.load` and ensure the new arguments are handled. Consider pinning `asyncssh<2.19.0` if immediate refactoring is not feasible.
affects: >=2.19.0
breakingSubclasses of `asyncssh.sftp.SFTPServer` that implement their own `__init__` method will need to update their signature in AsyncSSH 2.x to pass arguments through to the parent class.
fix
Adjust `SFTPServer` subclass `__init__` methods to correctly call `super().__init__(...)` with the expected arguments.
affects: >=2.0.0
gotchaBefore Python 3.10, using `asyncio.Lock()` as a global variable could lead to `RuntimeError: 'asyncio.Lock' object is not bound to a distinct event loop` when `asyncio.run()` creates a new event loop. While not specific to AsyncSSH, this is a common footgun in `asyncio`-heavy applications.
fix
Ensure `asyncio.Lock` instances (and similar `asyncio` primitives) are created within the scope of the event loop where they will be used, or use Python 3.10+ where this issue is mitigated.
affects: <3.10 (Python)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'asyncssh'
The 'asyncssh' module is not installed in the Python environment.
fix
Install the module using pip: 'pip install asyncssh'.
ImportError: cannot import name 'SSHClient' from 'asyncssh'
The 'SSHClient' class does not exist in the 'asyncssh' module.
fix
Use 'asyncssh.connect()' to establish SSH connections instead of importing 'SSHClient'.
TypeError: 'NoneType' object is not iterable
An SSH connection attempt failed, returning 'None', which is not iterable.
fix
Ensure the SSH server is accessible and the connection parameters are correct before attempting to iterate over the connection object.
asyncssh.misc.DisconnectError: Disconnect Error: Connection lost
The SSH connection was unexpectedly terminated.
fix
Check the network stability and ensure the SSH server is running and accessible.
asyncssh.public_key.KeyImportError: Key is not in a recognized format
The provided SSH key is in an unsupported or corrupted format.
fix
Verify the SSH key format and ensure it is correctly generated and not corrupted.
Upgrade
Version history
2.24.0latest on PyPI · released Jun 27, 2026
Audit
Dependencies
cryptographyrequiredRequired for core cryptographic functions. AsyncSSH 2.0+ requires cryptography >=39.0.
bcryptoptionalOptional, for OpenSSH private key encryption.
fido2optionalOptional, for U2F/FIDO2 security key authentication.
gssapioptionalOptional, for GSSAPI key exchange and authentication (UNIX-like systems).
ifaddroptionalOptional, for network interface address information.
pkcs11optionalOptional, for accessing PIV security tokens.
pyOpenSSLoptionalOptional, for X.509 certificate authentication.
pywin32optionalOptional, for Pageant agent support and GSSAPI on Windows.
Agent activity
57 hits · last 30 days
node
48
OpenAI (training)
1
Resources
asyncssh — pip install asyncssh · libregistry