{"id":10261,"library":"ssh-python","title":"ssh-python Library","description":"ssh-python provides robust Python bindings for the `libssh` C library, enabling programmatic interaction with SSH servers. It offers functionalities for connecting, authenticating, executing commands, and managing SSH channels. The library is actively maintained, with version 1.2.0.post1 being the latest stable release, typically releasing minor updates every few months with periodic patch versions.","status":"active","version":"1.2.0.post1","language":"en","source_language":"en","source_url":"https://github.com/ParallelSSH/ssh-python","tags":["ssh","libssh","networking","remote-execution","system-administration"],"install":[{"cmd":"pip install ssh-python","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core C library wrapper. Wheels embed libssh, but source builds require system libssh development headers.","package":"libssh","optional":false}],"imports":[{"symbol":"Session","correct":"from ssh import Session"},{"symbol":"AuthError","correct":"from ssh import AuthError"},{"symbol":"SSHException","correct":"from ssh import SSHException"},{"symbol":"SSH_OPTIONS_HOST","correct":"from ssh import SSH_OPTIONS_HOST"},{"symbol":"SSH_AUTH_SUCCESS","correct":"from ssh import SSH_AUTH_SUCCESS"}],"quickstart":{"code":"import ssh\nimport os\n\ntry:\n    # Initialize an SSH session\n    session = ssh.Session()\n    \n    # Set connection options\n    session.options_set(ssh.SSH_OPTIONS_HOST, os.environ.get('SSH_HOST', 'localhost'))\n    session.options_set(ssh.SSH_OPTIONS_PORT, int(os.environ.get('SSH_PORT', 22)))\n\n    # Connect to the SSH server\n    session.connect()\n    print(f\"Connected to {session.options_get(ssh.SSH_OPTIONS_HOST)}:{session.options_get_int(ssh.SSH_OPTIONS_PORT)}\")\n\n    # Authenticate using password\n    username = os.environ.get('SSH_USER', 'guest')\n    password = os.environ.get('SSH_PASSWORD', 'guestpass') # DO NOT hardcode passwords in production\n\n    if session.userauth_password(username, password) != ssh.SSH_AUTH_SUCCESS:\n        raise ssh.AuthError(\"Authentication failed\")\n    print(f\"Authenticated as {username}\")\n\n    # Open a channel for executing commands\n    channel = session.channel_session()\n    channel.open_session()\n    \n    # Execute a command\n    command = \"echo Hello from ssh-python!\"\n    print(f\"Executing command: '{command}'\")\n    channel.request_exec(command)\n    \n    # Read output\n    stdout = channel.read_stdout(2048)\n    stderr = channel.read_stderr(2048)\n    exit_status = channel.get_exit_status()\n\n    print(f\"--- STDOUT ---\\n{stdout.decode().strip()}\")\n    print(f\"--- STDERR ---\\n{stderr.decode().strip()}\")\n    print(f\"Exit Status: {exit_status}\")\n\n    # Close the channel and session\n    channel.close()\n    print(\"Channel closed.\")\n    session.disconnect()\n    print(\"Session disconnected.\")\n\nexcept ssh.AuthError as e:\n    print(f\"Authentication Error: {e}\")\nexcept ssh.SSHException as e:\n    print(f\"SSH Connection Error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your development and deployment environments use Python 3.8 or newer. Upgrade your Python installation if necessary.","message":"Older 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.","severity":"breaking","affected_versions":"<1.1.0"},{"fix":"For 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.","message":"Although 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).","severity":"gotcha","affected_versions":"All versions (for source builds)"},{"fix":"Upgrade to `ssh-python` 1.2.0 or newer to access the latest features and methods. Use `pip install --upgrade ssh-python`.","message":"API 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`.","severity":"breaking","affected_versions":"<1.2.0"},{"fix":"Double-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.","message":"Authentication failures are common due to incorrect credentials, invalid private key paths/permissions, or server-side configuration issues. The `AuthError` exception should be specifically handled.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the library: `pip install ssh-python`. Ensure your virtual environment is activated if you are using one.","cause":"The `ssh-python` library (which provides the `ssh` module) is not installed in the active Python environment or is not on the Python path.","error":"ModuleNotFoundError: No module named 'ssh'"},{"fix":"Verify your credentials (username, password, private key path). Check permissions of private key files (usually `chmod 600`). Review SSH server logs for authentication details (`/var/log/auth.log` on Linux).","cause":"The provided username, password, or private key is incorrect, or the SSH server denied the authentication attempt for other reasons (e.g., user not found, public key not authorized).","error":"ssh.AuthError: Authentication failed"},{"fix":"Check the hostname or IP address for typos. Verify network connectivity to the target host (e.g., `ping hostname`). Ensure the SSH service is running on the remote server.","cause":"The hostname or IP address provided for connection could not be resolved by DNS, or the server is unreachable/down.","error":"ssh.SSHException: Could not resolve hostname ..."},{"fix":"Upgrade your `ssh-python` library to version 1.2.0 or newer: `pip install --upgrade ssh-python`.","cause":"You are trying to call `get_exit_status()` on an `ssh.channel.Channel` object, but your installed `ssh-python` version is older than 1.2.0, where this method was introduced.","error":"AttributeError: 'Channel' object has no attribute 'get_exit_status'"}]}