xargs
Turns lines from standard input into command arguments
xargs reads words or lines from standard input and passes them as arguments to a command. This turns the output of find, grep -l or cat list into a list of files for rm, chmod, wc and other commands that don't read stdin.
Syntax
source-command | xargs [options] [command [initial arguments…]]
xargs -a file [options] [command …]
By default xargs splits input on spaces, tabs and newlines, understands quotes and \, gathers as many words as possible and runs the command as few times as possible. Without a command it runs echo.
How to split input
| Option | What it does |
|---|---|
| (default) | items are separated by spaces and newlines; quotes '…', "…" and \ join words |
-0 | items are separated by a null byte, quotes aren't special — the counterpart of find -print0, grep -lZ, sort -z |
-d '\n' | a custom separator (one character): -d '\n' — whole lines, -d , — comma-separated; quotes aren't special |
-a file | read items from a file, leaving stdin to the command |
-E STOP | stop reading when the item STOP is encountered |
How many arguments per run
| Option | What it does |
|---|---|
-n N | at most N arguments per run |
-L N | at most N non-empty input lines per run |
-I{} | substitute the item for {} anywhere in the command; the item is the whole line; one run per line |
-s N | at most N characters per command line |
-x | exit with an error if an item doesn't fit into -s/-n |
--show-limits | show the system limit on command line length |
How to run
| Option | What it does |
|---|---|
-r | don't run the command if the input is empty (GNU) |
-P N | run up to N commands in parallel; -P 0 — as many as possible |
--process-slot-var=VAR | with -P, pass each run its slot number in the variable VAR |
-t | print each command to stderr before running it |
-p | ask for confirmation before each run (needs a terminal) |
-o | connect the command's stdin to the terminal — for interactive programs (vim) |
Exit code
| Code | When |
|---|---|
0 | all runs of the command succeeded |
123 | at least one run returned 1–125 |
124 | the command returned 255 — xargs stopped |
125 | the command was killed by a signal |
126 / 127 | the command can't be run / wasn't found |
1 | an error in xargs itself (e.g. an unmatched quote) |
Examples
# delete all .tmp files, names with spaces don't break
find . -name '*.tmp' -print0 | xargs -0 rm --
# count lines in all .conf files that contain the word listen
grep -lZ 'listen' /etc/nginx/*.conf | xargs -0 wc -l
# two arguments per run: shows how xargs splits the input
echo a b c d e | xargs -n 2 echo
# put the item in the middle of the command
ls *.log | xargs -I{} cp {} /srv/backup/{}.old
# each line is one argument, even if it contains spaces
cat files.txt | xargs -d '\n' ls -l
# comma-separated items
printf 'alpha,beta,gamma' | xargs -d , -n 1 echo
# first see what will be run
find /var/log -name '*.gz' | xargs -t ls -lh
# compress files in 4 parallel jobs, one file per gzip
find /srv/app/logs -name '*.log' -print0 | xargs -0 -n 1 -P 4 gzip
# custom logic per item: the argument arrives in $1
find . -name '*.csv' -print0 | xargs -0 -n 1 sh -c 'echo "$1: $(wc -l < "$1") lines"' _
# do nothing if find found nothing
find . -name '*.bak' -print0 | xargs -0 -r rm --
# a list of hosts from a file, stdin stays free
xargs -a hosts.txt -n 1 ping -c 1
Pitfalls
- Spaces in names. Without
-0the filemy file.txtbecomes two arguments,myandfile.txt. Usefind -print0 | xargs -0or-d '\n'. - Quotes are special. Without
-0/-d,xargsparses quotes itself: the stringit'sgives the error "unmatched single quote", and the command isn't run. - Empty input. GNU
xargsstill runs the command once by default — with no arguments.xargs lson empty input lists the current directory, andxargs rmgives an error. Add-r. -Ichanges the mode: an item is the whole line (spaces don't split it, leading spaces are dropped), and the command runs separately for each line. That's slower than running in batches.-Land a trailing space. A line ending with a space is treated as continued:aandbend up in the same run.-d ,doesn't strip the newline at the end of input: withecho 'a,b' | xargs -d , …the last item isbwith\n. Feed input without it (printf) or split with-d '\n'aftertr ',' '\n'.-nand-Lare mutually exclusive — the last one given wins, andxargswarns.- Don't put
{}insidesh -c '…'. A file name with;or$(…)would run as code. Pass the item as an argument:sh -c '… "$1"' _. - The command's stdin is
/dev/null. A program that expects input (read,vim) gets nothing. For interactive commands use-o, for reading the list from a file —-a. - Order with
-Pisn't guaranteed: the output of parallel runs gets mixed.
See also
find · grep · rm · redirection · exit-codes · background