Install & Compatibility
Where this runs
tested against v0.3.5 · 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
installs and imports cleanly · install 0.0s · import 0.010s · 41.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.8s · import 0.010s · 42MB
40MB installed
● package 40MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SSHClientInteraction
✓ from paramiko_expect import SSHClientInteraction
This quickstart demonstrates how to establish an SSH connection using Paramiko, then wrap the SSHClient object with SSHClientInteraction to send commands and expect specific prompts. It prints the cleaned output of each command.
import paramiko
import os
from paramiko_expect import SSHClientInteraction
HOSTNAME = os.environ.get('SSH_HOSTNAME', 'localhost')
USERNAME = os.environ.get('SSH_USERNAME', 'testuser')
PASSWORD = os.environ.get('SSH_PASSWORD', 'testpass')
PROMPT = r'.*\$ ' # Example prompt for a Linux shell ending with $ or #
client = paramiko.SSHClient()
client.load_system_host_keys()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
try:
client.connect(hostname=HOSTNAME, username=USERNAME, password=PASSWORD, timeout=10)
print(f"SSH connection established to {HOSTNAME}")
with SSHClientInteraction(client, timeout=10, display=True) as interact:
# Wait for the initial prompt after connection
interact.expect(PROMPT)
print(f"Initial prompt: {interact.last_match}")
# Send a command and wait for the prompt again
interact.send('uname -a')
interact.expect(PROMPT)
print(f"Uname output:\n{interact.current_output_clean}")
# Send another command
interact.send('echo Hello paramiko-expect!')
interact.expect(PROMPT)
print(f"Echo output:\n{interact.current_output_clean}")
finally:
client.close()
print("SSH connection closed.")
Debug
Known issues
breakingPotential compatibility issues with newer Paramiko versions: paramiko-expect (v0.3.5) was last updated in November 2022. The underlying Paramiko library has had several major releases since then (e.g., Paramiko 3.x in December 2023), including dropping support for Python 2 and older Python 3 versions (<3.6). Using paramiko-expect with the very latest Paramiko releases might lead to unforeseen compatibility issues or unexpected behavior.fixPin your Paramiko dependency to a version known to be compatible with paramiko-expect v0.3.5 (e.g., Paramiko <3.0). If you require newer Paramiko features, thoroughly test for compatibility or consider alternatives.
affects: <0.3.5, Paramiko >= 3.0
gotchaOutput cleaning can break with long commands due to TTY width: If a command sent via `send()` is long enough to wrap lines within the remote terminal's `tty_width`, the echoed command line may contain inserted spaces. This can cause `current_output_clean` to fail to correctly remove the echoed command, resulting in it appearing in your captured output or breaking subsequent `expect()` calls based on output patterns.fixAdjust the `tty_width` parameter in `SSHClientInteraction` to match or exceed the maximum expected line length, or ensure your `expect()` patterns are robust enough to handle potential line wrapping in the echoed command.
affects: All versions
gotchaMisunderstanding `expect()` patterns for multi-line output/prompts: When expecting a prompt or output that spans multiple lines, users sometimes create complex regex patterns or lists expecting every line. Often, `interact.expect()` only needs to match the *final* line or a unique part of the prompt to correctly identify the state, and over-specifying can lead to timeouts or incorrect matches.fixSimplify `expect()` patterns to target only the distinctive end-of-prompt or end-of-output string. Test your patterns thoroughly to ensure they reliably match the desired state without being overly strict.
affects: All versions
gotcha`SSHClientInteraction` requires a `paramiko.SSHClient` object: The `SSHClientInteraction` class is designed to wrap a `paramiko.SSHClient` instance. While the library's description mentions potential future support for `paramiko.Transport` objects, currently, passing a `Transport` object directly will result in an error or incorrect behavior.fixAlways initialize `SSHClientInteraction` with a fully connected `paramiko.SSHClient` object. Ensure the `SSHClient` object has already established a session with `client.connect()` before passing it to `SSHClientInteraction`.
affects: All versions
Errors
Common errors & fixes
paramiko-expect timing out
The `interact.expect()` method did not find the expected pattern within the specified timeout duration, often due to an incorrect regular expression, slow remote host response, or an insufficient timeout value.
fixAdjust the regex pattern in `interact.expect()` to accurately match the remote host's prompt or output, increase the `timeout` parameter in the `SSHClientInteraction` constructor or the `expect()` method, or debug the remote process to ensure it's behaving as expected.
ImportError: No module named termios
The `termios` module, which `paramiko-expect` or its dependencies might try to import, is a Unix-specific module and is not available on non-Unix-like operating systems, most commonly Windows.
fixRun the `paramiko-expect` application on a Unix-like environment (e.g., Linux, macOS, or Windows Subsystem for Linux (WSL)) as `termios` is not supported on native Windows Python.
EXCESS TIME RECV_READY TIMEOUT, did you expect() before a send()
This internal diagnostic from `paramiko-expect` indicates that a `recv_ready` operation timed out because an `expect()` call was made without a preceding `send()` operation, or the `send()` command's output was not immediately followed by the expected prompt.
fixEnsure that every `interact.expect()` call is logically preceded by an `interact.send()` call (or initial `expect` for the first prompt) to await the output of a command, and verify that the remote host consistently sends a response after commands are issued.
AttributeError: 'SSHClient' object has no attribute 'expect'
This error occurs when a user incorrectly attempts to call the `expect()` method directly on a `paramiko.SSHClient` object, instead of on an `SSHClientInteraction` object which is the wrapper provided by `paramiko-expect`.
fixAfter connecting with `paramiko.SSHClient`, create an instance of `SSHClientInteraction` and use its methods for 'expect'-like interactions: `interact = SSHClientInteraction(client_object, timeout=10); interact.expect(prompt)`.
Upgrade
Version history
0.3.5latest on PyPI · released Nov 19, 2022
Audit
Dependencies
paramikorequiredparamiko-expect is a wrapper around the Paramiko SSH library and requires it for core SSH client functionality.