parallel-ssh (pssh)

2.16.0.post1 · active · verified Fri Apr 17

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.

Common errors

```
ModuleNotFoundError: No module named 'parallel_ssh'
```
cause 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
```
cause `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')
```
cause 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.
```
cause 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.

Warnings

breaking Python 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.
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.
gotcha Compression 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)`).
gotcha The 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.

Install

pip install parallel-ssh Install stable version

Imports

ParallelSSHClient

wrong:

from parallel_ssh.clients import ParallelSSHClient

correct:

from pssh.clients import ParallelSSHClient

The PyPI package `parallel-ssh` is imported as `pssh`.

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

Quickstart

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

view raw JSON →