Troubleshooting

Symptoms first, causes second, fixes third. The top entry is the first thing to try for almost everything.

"The commands look wrong"

They would have run anyway — that is the danger this tool carries. Make --dry-run a reflex:

parallel --dry-run <your whole command> ::: <your list>

Read the printed commands as literally as the shell will. Most "parallel did something insane" stories end here: the template was wrong in a way the dry run shows in one second.

A | or > in the template acted on the whole run

The template is a shell command line. This transcript t02 accident is the classic shape:

$ parallel echo '{} | {/} | {//}' ::: samples/north/notes-01.txt
samples/north/notes-01.txt
notes-01.txt
samples/north

The | was a real pipe, not a separator — the three values came out one per line instead of side by side. Fix: quote what is meant literally, or pick a separator that is not shell syntax (:: worked in the lab). The same applies to >: a redirection in a template is per-job only if the replacement string is inside it, as in chapter 10's > upper/{/.}.upper.

Output arrives scrambled

Jobs print in finish order by default. Add -k for input order (chapter 8). If individual lines are torn mid-line, something is streaming — look for --ungroup or --line-buffer in the command and drop them for collected output.

"command not found" inside jobs, fine outside

Your shell functions and aliases do not exist in the shells parallel spawns. Either use real commands and scripts, or meet the companion tool env_parallel, which captures your shell environment — functions included — for job use. A function exported with export -f in bash also crosses over.

The run is slower than the loop

Almost never the tool; almost always a shared bottleneck or tiny jobs (chapter 13). Lower -j, time one job alone, and check whether the disk or the network — not the CPU — is the busy part.

A run "hangs" at the end

One job is still running: the bar or job log shows which. Long tails are normal with mixed lists — the last slot holds the slowest job. --timeout caps it next time; the job log from this run tells you what it was.

parallel: command not found, or a strange old parallel

Two different tools answer to this name (chapter 3). parallel --version should answer with a GNU version line. If it does not, install the parallel package and check which parallel — the moreutils tool of the same name is the usual impostor.

A notice about citations appears in the logs

That is an upstream build asking, once, for a citation (chapter 3). parallel --citation settles it permanently. The Debian/Ubuntu package never prints it; if you see it, your parallel came from upstream or another distribution.

Exit status is a small number, not 1

By design: it is the count of failed jobs, capped at 100 (chapter 6). 0 means every job succeeded. Scripts should test "not zero", not "equals one".