← Full reference

shuf

Shuffle lines, pick random lines or numbers, generate a sample with repeats

shuf outputs lines in random order. With -n it takes a random sample, with -i it shuffles a range of numbers, with -e — its own arguments. Useful for test data, picking a random server or file, sampling lines from a big log.

Syntax

shuf [options] [file]            # lines of a file or standard input
shuf -e [options] [arg…]         # each argument is a line
shuf -i LO-HI [options]          # numbers from a range

shuf accepts one file. For several, join them first: cat a b | shuf.

Options

Source of lines

OptionWhat it does
(file or -)lines of a file or standard input
-e arg…each argument is a separate line
-i LO-HInumbers from LO to HI inclusive, one per line
-zlines are separated by a NUL byte, not \n (pairs with find -print0)

How many and how to pick

OptionWhat it does
-n Noutput at most N lines — a random sample without repeats
-rsample with repeats: the same line can come up several times. Without -n it outputs forever
-o filewrite the result to a file (it can be the same as the input)
--random-source=filetake random bytes from a file — for a reproducible result

Examples

seq 10 > items.txt

# shuffle lines
shuf items.txt

# one random line
shuf -n 1 items.txt

# three random numbers from 1 to 100 without repeats
shuf -i 1-100 -n 3

# pick from options
shuf -n 1 -e red green blue

# 5 coin flips — with repeats
shuf -r -n 5 -e H T

# 10 dice rolls
shuf -r -n 10 -i 1-6

# shuffle a file in place
shuf -o items.txt items.txt

# a random sample of 100 lines from a log
shuf -n 100 /var/log/dpkg.log

# reproducible order: the same "seed" gives the same result
seeded() { openssl enc -aes-256-ctr -pass pass:"$1" -nosalt </dev/zero 2>/dev/null; }
shuf -n 3 --random-source=<(seeded 42) items.txt
shuf -n 3 --random-source=<(seeded 42) items.txt   # the same

# a random file from a directory (names with spaces — via -z)
find /etc -maxdepth 1 -type f -print0 | shuf -z -n 1 | tr '\0' '\n'

Pitfalls

  • -r without -n never stops: shuf -r -e a b prints forever. Always limit it with -n or head.
  • -n larger than the number of lines is not an error. shuf -i 1-3 -n 10 prints three numbers: without -r there are no repeats, and there's nothing more to take.
  • A second file is an error: shuf a b gives extra operand 'b'. Join files with cat.
  • shuf file > file truncates the file before reading it. For writing in place there's -o file.
  • --random-source with a short file fails with end of file: lots of random bytes are needed. A regular file as a "seed" only works if it's large; it's more reliable to generate a stream from a password via openssl enc, as in the example.
  • Empty input is not an error. shuf -e without arguments and shuf -n 1 on an empty file print nothing and return 0. Check the result before substituting it into a command.
  • -i accepts only non-negative integers in ascending order: shuf -i 5-1 is an invalid input range error.

See also

seq · sort · head and tail · find · openssl