← Full reference

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

OptionWhat it does
(default)items are separated by spaces and newlines; quotes '…', "…" and \ join words
-0items 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 fileread items from a file, leaving stdin to the command
-E STOPstop reading when the item STOP is encountered

How many arguments per run

OptionWhat it does
-n Nat most N arguments per run
-L Nat 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 Nat most N characters per command line
-xexit with an error if an item doesn't fit into -s/-n
--show-limitsshow the system limit on command line length

How to run

OptionWhat it does
-rdon't run the command if the input is empty (GNU)
-P Nrun up to N commands in parallel; -P 0 — as many as possible
--process-slot-var=VARwith -P, pass each run its slot number in the variable VAR
-tprint each command to stderr before running it
-pask for confirmation before each run (needs a terminal)
-oconnect the command's stdin to the terminal — for interactive programs (vim)

Exit code

CodeWhen
0all runs of the command succeeded
123at least one run returned 1–125
124the command returned 255 — xargs stopped
125the command was killed by a signal
126 / 127the command can't be run / wasn't found
1an 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 -0 the file my file.txt becomes two arguments, my and file.txt. Use find -print0 | xargs -0 or -d '\n'.
  • Quotes are special. Without -0/-d, xargs parses quotes itself: the string it's gives the error "unmatched single quote", and the command isn't run.
  • Empty input. GNU xargs still runs the command once by default — with no arguments. xargs ls on empty input lists the current directory, and xargs rm gives an error. Add -r.
  • -I changes 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.
  • -L and a trailing space. A line ending with a space is treated as continued: a and b end up in the same run.
  • -d , doesn't strip the newline at the end of input: with echo 'a,b' | xargs -d , … the last item is b with \n. Feed input without it (printf) or split with -d '\n' after tr ',' '\n'.
  • -n and -L are mutually exclusive — the last one given wins, and xargs warns.
  • Don't put {} inside sh -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 -P isn't guaranteed: the output of parallel runs gets mixed.

See also

find · grep · rm · redirection · exit-codes · background