cheatsheet

parallel-ssh in Linux: Syntax, Options & Parallel SSH Examples

The pssh package provides parallel-ssh, parallel-scp, parallel-slurp, parallel-nuke, and parallel-rsync — Python tools that fan out SSH, copy, and rsync jobs across many hosts from one control node using a host list file or inline -H entries.

Published

Updated

Read time 7 min read

Reviewed byDeepak Prasad

parallel-ssh in Linux: Syntax, Options & Parallel SSH Examples
About The pssh package provides parallel-ssh, parallel-scp, parallel-slurp, parallel-nuke, and parallel-rsync — Python tools that fan out SSH, copy, and rsync jobs across many hosts from one control node using a host list file or inline -H entries.
Tested on Ubuntu 25.04 (Plucky Puffin); pssh 2.3.5-2; OpenSSH client; kernel 7.0.0-27-generic
Package pssh (apt/deb) · pssh (dnf/rpm)
Man page parallel-ssh(1)
Privilege SSH access to targets; root only when remote command requires it
Distros

Ubuntu and Debian: sudo apt install pssh.

Binaries: parallel-ssh, parallel-scp, parallel-slurp, parallel-nuke, parallel-rsync. There is no pssh executable in package 2.3.5.

parallel-ssh — quick reference

Run remote commands (parallel-ssh)

Host file format: one [user@]host[:port] per line. -h requires a filename — it is not --help.

When to use Command
Run a command on every host in a file parallel-ssh -h hosts.txt -l USER COMMAND
Add hosts on the command line parallel-ssh -H "host1 host2" -l USER COMMAND
Print each host's stdout inline parallel-ssh -i -h hosts.txt -l USER COMMAND
Stream output as it arrives parallel-ssh -P -h hosts.txt -l USER COMMAND
Limit parallel SSH sessions parallel-ssh -p 5 -h hosts.txt -l USER COMMAND
Per-host timeout in seconds (0 = none) parallel-ssh -t 30 -h hosts.txt -l USER COMMAND
Save stdout/stderr per host to directories parallel-ssh -o /tmp/out -e /tmp/err -h hosts.txt -l USER COMMAND
Pass OpenSSH config-style option parallel-ssh -O StrictHostKeyChecking=no -h hosts.txt -l USER COMMAND
Extra ssh arguments (split on whitespace) parallel-ssh -x "-o ConnectTimeout=5" -h hosts.txt -l USER COMMAND
Single raw ssh argument parallel-ssh -X "-tt" -h hosts.txt -l USER COMMAND
Pipe local stdin to remote command echo date | parallel-ssh -I -h hosts.txt -l USER
Filter hosts with shell glob parallel-ssh -g "web*" -h hosts.txt -l USER COMMAND
Prompt for SSH password parallel-ssh -A -h hosts.txt -l USER COMMAND
Verbose diagnostics parallel-ssh -v -h hosts.txt -l USER COMMAND

Copy files (parallel-scp)

When to use Command
Upload a file to the same path on all hosts parallel-scp -h hosts.txt -l USER localfile /remote/path/
Recursive directory upload parallel-scp -r -h hosts.txt -l USER localdir /remote/
Download from each host into host-named dirs parallel-scp --download -h hosts.txt -l USER /remote/file ./local/

Pull files (parallel-slurp)

When to use Command
Copy the same remote path from many hosts into local subdirectories parallel-slurp -h hosts.txt -l USER /var/log/syslog ./collected/

Sync directories (parallel-rsync)

When to use Command
Rsync a local tree to the same path on all hosts parallel-rsync -h hosts.txt -l USER /local/dir/ /remote/dir/

parallel-nuke

When to use Command
Run pkill -9 matching a pattern on every host (destructive) parallel-nuke -h hosts.txt -l USER PATTERN

Help and version

When to use Command
Show options (-h is hosts file on these tools) parallel-ssh --help
Package version parallel-ssh --version

parallel-ssh — command syntax

Synopsis from parallel-ssh --help on Ubuntu 25.04 (pssh 2.3.5):

text 
Usage: parallel-ssh [OPTIONS] command [...]

Options:
  -h HOST_FILE, --hosts=HOST_FILE
  -H HOST_STRING, --host=HOST_STRING
  -l USER, --user=USER
  -p PAR, --par=PAR
  -o OUTDIR, --outdir=OUTDIR
  -e ERRDIR, --errdir=ERRDIR
  -t TIMEOUT, --timeout=TIMEOUT
  -O OPTION, --option=OPTION
  ...

parallel-ssh opens one SSH session per host (throttled by -p). Authentication uses your normal OpenSSH setup — keys, agent, or -A for password prompt.

parallel-ssh — command examples

Essential Host file and basic command

Create a host list and run a command on each entry. Localhost tests below use root with key auth — replace with your fleet user and hostnames.

bash 
echo 127.0.0.1 > /tmp/hosts.txt
parallel-ssh -h /tmp/hosts.txt -l root -O StrictHostKeyChecking=no hostname

Sample output:

text 
[1] 18:29:30 [SUCCESS] 127.0.0.1

[SUCCESS] means SSH connected and the remote command exited 0.

Essential Inline hosts with -H

Skip a host file when you only have a few machines.

bash 
parallel-ssh -H "127.0.0.1" -l root -O StrictHostKeyChecking=no uptime

Sample output:

text 
[1] 18:29:31 [SUCCESS] 127.0.0.1

Add -i to print each host's command output under the status line.

Essential Inline aggregated output with -i
bash 
parallel-ssh -i -h /tmp/hosts.txt -l root -O StrictHostKeyChecking=no 'echo hello'

Sample output:

text 
[1] 18:29:31 [SUCCESS] 127.0.0.1
hello
Common Throttle parallelism with -p

-p caps concurrent SSH sessions — useful on large clusters or fragile networks.

bash 
parallel-ssh -p 1 -h /tmp/hosts.txt -l root -O StrictHostKeyChecking=no date

Sample output:

text 
[1] 18:29:32 [SUCCESS] 127.0.0.1

With twenty hosts and -p 5, parallel-ssh starts five workers and schedules the rest as slots free up.

Common Per-host stdout and stderr directories

Automation scripts parse one file per host under -o and -e.

bash 
OUT=$(mktemp -d)
ERR=$(mktemp -d)
parallel-ssh -h /tmp/hosts.txt -l root -O StrictHostKeyChecking=no -o "$OUT" -e "$ERR" 'uname -s'
ls "$OUT"
cat "$OUT"/*
rm -rf "$OUT" "$ERR"

Sample file content:

text 
Linux

Empty files in $ERR usually mean success.

Common Upload a file with parallel-scp

parallel-scp uses the same host file format as parallel-ssh.

bash 
echo "test content" > /tmp/deploy.txt
parallel-scp -h /tmp/hosts.txt -l root -O StrictHostKeyChecking=no /tmp/deploy.txt /tmp/deploy.txt
ssh -o StrictHostKeyChecking=no [email protected] cat /tmp/deploy.txt
ssh -o StrictHostKeyChecking=no [email protected] rm -f /tmp/deploy.txt
rm -f /tmp/deploy.txt

Sample parallel-scp status:

text 
[1] 18:29:34 [SUCCESS] 127.0.0.1

Remote verification prints test content.

Common Pass SSH options with -O and -x

-O maps to ssh -o KEY=VALUE. -x forwards multiple ssh flags with shell splitting.

bash 
parallel-ssh -h /tmp/hosts.txt -l root -O StrictHostKeyChecking=no -O ConnectTimeout=5 hostname
parallel-ssh -h /tmp/hosts.txt -l root -x "-o StrictHostKeyChecking=no -o ConnectTimeout=5" hostname

Any option from ssh_config(5) that your OpenSSH client supports can be forwarded

Advanced Timeouts and [FAILURE] status

-t sets a per-host timeout in seconds. Unreachable hosts or hung commands show [FAILURE].

bash 
parallel-ssh -t 2 -h /tmp/hosts.txt -l root -O StrictHostKeyChecking=no sleep 60

Sample output when the host is unreachable:

text 
[1] 18:30:01 [FAILURE] 192.0.2.99

Combine -i with -e output directories to capture stderr for post-run summaries.

Advanced Passwordless runs with SSH keys

Configure keys once on the control node, then parallel-ssh needs no -A prompt.

bash 
ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519
ssh-copy-id user@bastion
parallel-ssh -h hosts.txt -l user uptime

See generate SSH keys for key types and permissions (chmod 600 private key, 700 .ssh).

parallel-ssh — when to use / when not

Use parallel-ssh when Use something else when
  • You must run the same command or script on tens or hundreds of Linux hosts
  • You want simple fan-out without installing agents on targets
  • You need parallel scp or rsync from one control node
  • SSH key auth is already configured to your fleet
  • You manage one host → plain ssh
  • You need idempotent config enforcement → Ansible, Salt, Puppet
  • You need complex orchestration with rollback → configuration management or CI pipelines
  • Hosts are Windows → WinRM / Ansible win_shell, not parallel-ssh
  • You need interactive TUI per host → Cluster SSH (cssh) or terminal multiplexing

parallel-ssh vs Ansible ad-hoc

parallel-ssh (pssh package) Ansible
Setup Host file + SSH keys Inventory + playbooks
Learning curve Low — wraps ssh Higher — YAML modules
Idempotency None — runs raw command Module design
Best for Quick fleet commands, log collection Ongoing config management
Command One line
parallel-ssh Parallel remote commands (this page)
rsync Incremental sync (serial)

Browse the full index in our Linux commands reference.

parallel-ssh — interview corner

What is the pssh package?

The Debian/Ubuntu pssh package installs parallel-ssh, parallel-scp, parallel-slurp, parallel-nuke, and parallel-rsync. There is no pssh binary in 2.3.5 — run parallel-ssh instead.

A strong answer is:

"pssh is the package name; the command I run is parallel-ssh, plus parallel-scp and parallel-rsync for copies."

What goes in the host file?

One host per line: optional user@, hostname or IP, optional :port. Example: [email protected]:22.

A strong answer is:

"One [user@]host[:port] per line — parallel-ssh -h reads that file."

What does -p control?

-p sets the maximum parallel SSH sessions (thread pool size). It is not the SSH port — use :port in the host file or -O Port=N.

A strong answer is:

"-p limits concurrent connections — I tune it so I don't overwhelm the network or target sshd."

Difference between -i and -P?

-i prints each host's output inline after the status line when the command finishes. -P prints output as it streams during execution.

A strong answer is:

"-i aggregates inline output per host; -P streams output live as it arrives."

When use parallel-scp?

When the same file or tree must land on many hosts at once. Single destination copy still uses scp.

A strong answer is:

"parallel-scp fans out one upload to many hosts — same host file as parallel-ssh."

Troubleshooting

Symptom Likely cause What to try
parallel-ssh: error: -h option requires 1 argument Used -h for help Run parallel-ssh --help
[FAILURE] on all hosts Wrong user, key, or firewall ssh -l USER host manually; check -O ConnectTimeout
No output without -i Default shows status only Add -i or -P, or read -o directory files
Hangs on many hosts Too many parallel sessions Lower -p; raise MaxStartups on sshd carefully

References

Localhost examples use 127.0.0.1 with SSH keys. For parallel-slurp, parallel-nuke, and multi-host failure scenarios, test on disposable VMs before using them in production.

Deepak Prasad

R&D Engineer

Founder of GoLinuxCloud with more than 15 years of expertise in Linux, Python, Go, Laravel, DevOps, Kubernetes, Git, Shell scripting, OpenShift, AWS, Networking, and Security. With extensive …

Related Articles

security

Automate keytool Certificate Import in Bash Safely

Back up a PKCS12 truststore, check the keytool alias and SHA-256 fingerprint, import a CA only when missing, …

7 min readcheatsheet

screen Command in Linux: Syntax, Sessions, Windows & Key Bindings

GNU screen is a terminal multiplexer that keeps shell sessions alive after disconnect, supports multiple …

9 min readcheatsheet

crontab Command in Linux: Schedule Jobs, Syntax & Examples

crontab installs and edits per-user cron tables — the schedule files the cron daemon reads to run commands at …

9 min read