AsyncSSH

Warnings

• breaking AsyncSSH 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.
• breaking AsyncSSH 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.
• breaking In 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.
• breaking Starting 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.
• breaking Subclasses 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.
• gotcha Before 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.

Install

• pip install asyncssh Basic Installation
• pip install 'asyncssh[bcrypt,fido2,gssapi,ifaddr,pkcs11,pyopenssl,pywin32]' Installation with all optional dependencies (e.g., on UNIX)

Imports

• asyncssh

  import asyncssh

  Primary library import.
• asyncio

  import asyncio

  Required as AsyncSSH is built on asyncio.

Quickstart

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())