Registry / devops / parallel-ssh

parallel-ssh

JSON →
library2.16.0.post1pypypi✓ verified 85d ago

parallel-ssh, imported as `pssh`, is an asynchronous Python library for executing commands and transferring files over SSH to multiple hosts in parallel. It leverages `asyncio` for high-performance operations, making it suitable for managing large clusters or performing fast, concurrent remote tasks. The current version is 2.16.0.post1, and it maintains a relatively active release cadence with minor updates every few months.

pip install parallel-ssh
INSTALL
IMPORT
SIG · PARALLEL-SSH
P
parallel-ssh
devopspythonv2.16.0.post1
Install
3.1s avg
Import
189ms
Disk
57MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.16.0.post1 · 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
✕ build_error
✓ 3.55s
py 3.11
✕ build_error
✓ 3.1s
py 3.12
✕ build_error
✓ 2.9s
py 3.13
✕ build_error
✓ 2.95s
py 3.9
✕ build_error
✕ build_error
57MB installed
● package 57MB
Code
Verified usage

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

ParallelSSHClient
from pssh.clients import ParallelSSHClient
from parallel_ssh.clients import ParallelSSHClient
The PyPI package `parallel-ssh` is imported as `pssh`.
SSHClient
from pssh.clients import SSHClient
from parallel_ssh.clients import SSHClient
The PyPI package `parallel-ssh` is imported as `pssh`.

This quickstart demonstrates connecting to multiple hosts using `ParallelSSHClient` and executing a command. It uses `asyncio` to run the asynchronous operations. Replace `hostname1`, `hostname2`, and `your_user` with your actual host details and username. For authentication, consider using SSH agents, `known_hosts`, or passing credentials/private key paths to the client.

import asyncio from pssh.clients import ParallelSSHClient import os async def run_remote_commands(): # Replace with your actual hostnames or IP addresses hosts = ['hostname1', 'hostname2'] # You can specify username, password, or private key path # client = ParallelSSHClient(hosts, user='myuser', password=os.environ.get('SSH_PASSWORD', '')) # client = ParallelSSHClient(hosts, user='myuser', pkey='/path/to/id_rsa') client = ParallelSSHClient(hosts, user=os.environ.get('SSH_USER', 'your_user')) print(f"Connecting to {hosts} and running 'ls -l /tmp'...") output = await client.run_command('ls -l /tmp') async for host_output in output: print(f"\n--- Host: {host_output.host} ---") print(f"Return Code: {host_output.return_code}") print("Stdout:") for line in host_output.stdout: print(f" {line}") print("Stderr:") for line in host_output.stderr: print(f" {line}") if __name__ == '__main__': # Ensure your SSH_USER env var is set or replace 'your_user' directly # Also, ensure SSH agents or known_hosts are configured for passwordless access # or provide password/pkey arguments to ParallelSSHClient. asyncio.run(run_remote_commands())
parallel-ssh --version
Debug
Known issues
breakingPython 3.8+ is now required. Support for Python versions prior to 3.8 was dropped in `parallel-ssh` version 2.13.0.
fix
Upgrade your Python environment to 3.8 or newer if you are using `parallel-ssh` version 2.13.0 or later.
affects: >=2.13.0
gotcha`SSHClient.disconnect()` is a no-op since version 2.14.0. Individual `SSHClient` instances now manage their own disconnection upon de-allocation.
fix
Remove explicit calls to `SSHClient.disconnect()`. The client will handle resource cleanup automatically. Relying on explicit calls will not close the connection and may lead to resource leaks.
affects: >=2.14.0
gotchaCompression is opt-in. As of version 2.15.0, `parallel-ssh` supports compression, but it is not enabled by default for clients.
fix
To enable compression, explicitly pass `compress=True` when initializing `SSHClient`, `ParallelSSHClient`, or `HostConfig` (e.g., `ParallelSSHClient(hosts, compress=True)`).
affects: >=2.15.0
gotchaThe PyPI package `parallel-ssh` installs as the `pssh` Python module. Attempting to import `parallel_ssh` will result in a `ModuleNotFoundError`.
fix
Always use `from pssh.clients import ParallelSSHClient` (or `import pssh`) to import the library components.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'parallel_ssh'
The PyPI package `parallel-ssh` is imported as the `pssh` Python module.
fix
Change your import statements from `import parallel_ssh` (or similar) to `import pssh` or `from pssh.clients import ParallelSSHClient`.
TypeError: object NoneType can't be used in 'await' expression
`parallel-ssh` clients are asynchronous and their methods (e.g., `run_command`, `put_file`) must be `await`ed.
fix
Ensure you are calling `parallel-ssh` methods with the `await` keyword within an `async` function, and that your main script is run via `asyncio.run()`.
[Errno -1] Authentication failed (or similar SSH authentication error messages like 'Permission denied')
Incorrect SSH credentials (username, password, private key path), wrong private key passphrase, or issues with host key verification (`known_hosts`).
fix
Verify the `user`, `password`, `pkey`, and `passphrase` arguments passed to your `SSHClient` or `ParallelSSHClient`. Ensure target hosts' public keys are correctly added to your `~/.ssh/known_hosts` file, or consider explicitly disabling strict host key checking for development (not recommended for production).
RuntimeWarning: Enable asyncio debug mode to show full stack traces.
This is a common warning from `asyncio` when debug mode is not enabled, not an error specific to `parallel-ssh`. It indicates that `asyncio` will not provide full stack traces, which can make debugging harder.
fix
To enable debug mode, set the environment variable `PYTHONASYNCIODEBUG=1` before running your script, or call `asyncio.get_event_loop().set_debug(True)` early in your program.
Upgrade
Version history
2.16.0.post1latest on PyPI · released Oct 14, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
parallel-ssh — pip install parallel-ssh · libregistry