# shuf

_Peios / Using Peios / Peiosutils / Transforming text_

> Output the input lines in a random order.

`shuf` shuffles: it outputs its input lines in a random order. Every possible ordering is equally likely.

```
shuf [options] [file]
shuf -e [options] arg...
shuf -i lo-hi [options]
```

```
$ shuf playlist.txt
```

`shuf` is the opposite of [`sort`](/peios/using-peios/peiosutils/transforming-text/sort.md) — instead of imposing an order, it removes one. With no file, it reads standard input.

## Where the lines come from

`shuf` has three ways of getting its input, one per usage form:

| Option | Input is… |
|---|---|
| (a file, or stdin) | the lines of the file. |
| `-e`, `--echo` | the command-line arguments, each treated as one line. |
| `-i`, `--input-range=LO-HI` | the integers from `LO` to `HI`, each treated as one line. |

```
$ shuf -e red green blue          # shuffle three given words
$ shuf -i 1-100                   # the numbers 1..100 in random order
```

## Shaping the output

| Option | Effect |
|---|---|
| `-n`, `--head-count=COUNT` | Output at most `COUNT` lines — a random *sample* rather than the whole shuffle. |
| `-r`, `--repeat` | Allow lines to be repeated, so output can be longer than the input. Pair with `-n` to set how many. |
| `-o`, `--output=FILE` | Write to `FILE` instead of standard output. |
| `-z`, `--zero-terminated` | Treat the NUL character as the line delimiter. |

`shuf -n 1` is a common idiom — pick one random line.

## Reproducible shuffles

A shuffle is random by default. To get the *same* shuffle every time — for a repeatable test, say — fix the randomness:

| Option | Effect |
|---|---|
| `--random-seed=STRING` | Seed the shuffle with `STRING`. The same seed gives the same shuffle. |
| `--random-source=FILE` | Take the random bytes from `FILE`. The same file gives the same shuffle. Cannot be combined with `--random-seed`. |

## Exit status

| Code | Meaning |
|---|---|
| `0` | Success. |
| `1` | A failure — the input could not be read, or `-r` was used with no lines to repeat. |

Related content:

- [sort](/peios/using-peios/peiosutils/transforming-text/sort.md)
- [Transforming text](/peios/using-peios/peiosutils/transforming-text/overview.md)