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

Tested on Ubuntu 25.04 (Plucky Puffin)
Package pssh 2.3.5-2
pssh 2.3.5-2
Applies to Ubuntu, Debian, Kali Linux, Linux Mint, Pop!_OS, Raspberry Pi OS, RHEL, Rocky Linux, AlmaLinux, Oracle Linux, CentOS Stream, Fedora, Arch Linux
Privilege sudo or root
Man page parallel-ssh(1)
Scope 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.
Related guides Linux commands

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:

output
[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:

output
[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:

output
[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:

output
[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 root@127.0.0.1 cat /tmp/deploy.txt
ssh -o StrictHostKeyChecking=no root@127.0.0.1 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

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: root@10.0.0.5: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 experience, he excels across development, DevOps, networking, and security, delivering robust and efficient solutions for diverse projects.

Expertise
  • Go (programming language)
  • Python (programming language)
  • DevOps
  • Computer Security
  • Cloud Computing
  • Kubernetes
  • Linux
  • Ansible (software)

Related Articles

linux

Configure SSH Key Authentication in Linux

Set up SSH public key authentication with ssh-keygen, ssh-copy-id, and authorized_keys—connect with a specific …

13 min readsecurity

Fix OpenLDAP Invalid Credentials Error 49

Fix OpenLDAP Error 49 for wrong bind DNs, passwords, userPassword ACLs, locked accounts, expired passwords, …

16 min readsecurity

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 read