Skip to content
Tutorials Center
My learning

Topics

Linux Command Reference ยท Text Processing

Linux join command

Reference for the Linux join command: combine two sorted files on a shared key field, use -1 -2 -t -a -v -o, handle unmatched lines and unsorted input.

join combines two files line by line, like a database join: for every pair of lines that have the same value in a chosen key field, it prints the key followed by the remaining fields of both lines. It is the command-line equivalent of an SQL inner join, with options to also keep unmatched lines (outer joins).

Both files must be sorted on the join field, using the same ordering join expects. Fields are separated by blanks unless you set another separator with -t.

Terminal
join [OPTION]... FILE1 FILE2

Try it

Bash Inner join and unmatched lines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Other key fields, separators and sorting

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
join [-1 FIELD] [-2 FIELD] [-j FIELD] [-t CHAR] [-a FILENUM] [-v FILENUM] [-e STR] [-o FORMAT] [-i] FILE1 FILE2

One of the files may be - for standard input.

Option Description
-1 N, -2 N Join on field N of file 1 / file 2 (default 1).
-j N Same field N in both files.
-t CHAR Field separator for input and output (default: runs of blanks).
-a N Also print unpairable lines from file N (1 or 2).
-v N Print only unpairable lines from file N, suppress the paired lines.
-e STR Replace missing fields with STR (used with -o or -a).
-o LIST Output format: comma-separated FILE.FIELD, such as 1.1,2.3, or 0 for the join field. auto uses the first line to decide.
-i Ignore case when comparing keys.
--header Treat the first line of each file as a header and print it first.
--check-order, --nocheck-order Insist on / disable the sort-order check.
-z Lines end with NUL.

Default output: the join field, then the other fields of the line from file 1, then the other fields of the line from file 2.

Returns: 0 on success, 1 on error (including, with --check-order, unsorted input).

Usage notes

  • Sort both files first on the join field with the same locale as join: join <(sort file1) <(sort file2). Setting LC_ALL=C for both sort and join avoids locale mismatches.
  • Many-to-many: if a key occurs several times in both files, join prints every combination, like a SQL join.
  • Separator sorting: when you set -t, also sort with -t, and -k: sort -t, -k3,3.
  • Field numbers in -o count from 1 inside each file's line, not after the key has been moved. The join field itself is 0.
  • Missing keys: an inner join silently drops unmatched lines, which hides data problems. Use -v1 and -v2 to see what did not match.
  • Blank-separated default collapses runs of blanks. An empty field cannot occur there; use -t with a real separator for data that has empty values.
  • Alternatives: for positional pairing use paste; for set membership only, comm; for unsorted data or more complex logic, awk with an array lookup.