← Full reference

nl

Number lines — all, non-empty only or by pattern, with your own number format

nl (number lines) prints a file with line numbers. Unlike cat -n, it gives fine control: which lines to number (all, non-empty, matching a regex), starting number and increment, number width, with or without zeros, and what to put after the number.

Syntax

nl [options] [file…]

With no files or with - it reads standard input. Several files are numbered continuously, as one.

Options

Which lines to number

OptionWhat it does
-b anumber all lines, including empty ones
-b tnon-empty only (the default). A line of only spaces counts as non-empty
-b nnumber nothing
-b p'regex'only lines matching a basic regex (BRE), e.g. -b p'^#'
-l Nwith -b a: a group of N consecutive empty lines counts as one line, only every N-th gets a number

Number format

OptionWhat it does
-n rnright-aligned, no zeros (the default): 1
-n lnleft-aligned: 1
-n rzright-aligned with leading zeros: 000001
-w Nwidth of the number field (default 6)
-s STRINGwhat to put after the number (default a tab), e.g. -s '. '
-v Nfirst number (default 1)
-i Nincrement (default 1)

Unnumbered lines get spaces of the same width instead of a number, so the text stays aligned.

Logical pages

nl understands "page" markup: a \:\:\: line starts a header, \:\: — a body, \: — a footer. The delimiter lines themselves are replaced with empty lines, and numbering restarts on each page.

OptionWhat it does
-h STYLEhow to number the header (default n — not at all)
-f STYLEhow to number the footer (default n)
-pdon't reset the number on a new page
-d CHARSother delimiter characters instead of \:; -d '' disables page markup

STYLE takes the same values as -b: a, t, n, pREGEX.

Examples

printf 'one\n\ntwo\n# note\nthree\n' > notes.txt

# default: empty lines without a number
nl notes.txt

# all lines, like cat -n
nl -b a notes.txt

# comments only
nl -b p'^#' notes.txt

# compact: "1. text"
nl -w1 -s'. ' notes.txt

# with leading zeros, width 3
nl -n rz -w3 notes.txt

# start at 100, increment 10
nl -v 100 -i 10 notes.txt

# number a command's output
ls /etc | head -n 5 | nl

# line number for a grep-like search — via nl and grep
nl -b a notes.txt | grep two

Pitfalls

  • Empty lines aren't numbered by default, so a number from nl may not match the line number in the file (as in sed -n 5p or grep -n). For real line numbers use nl -b a or cat -n.
  • A \: line in the data gets eaten. nl takes it for page markup: the line disappears (replaced by an empty one), and the following lines land in the "footer" and stop being numbered. If such lines can occur in the text, add -d ''.
  • -w is a minimum width, not truncation. The number 12 with -w1 is still printed in full, the text after it just stops being aligned.
  • Width and separator together. With -n ln the padding spaces go after the number and before the separator: -n ln -w2 -s'. ' gives 1 . text. For the 1. text format use -w1.
  • -b p uses basic regexes (BRE). +, ?, | without a backslash are ordinary characters there. More on the regex page.
  • A line of spaces isn't empty. -b t will number it; only a line with no characters at all counts as empty.

See also

cat and tac · grep · sed · regex · column · wc