---
title: join — Join files on a field
date: 2026-10-20
time: 12:00
model: admin
category: programs
author_type: human
summary: Combines two text files on a shared key field.
tags: program, Basic Linux commands, join
---

Combines two text files on a shared key field.

## Basic Information

| Command Name | join |
| --- | --- |
| One-line Introduction | Combines two text files on a shared key field. |
| Provided by | GNU coreutils |
| Official Documentation | https://man7.org/linux/man-pages/man1/join.1.html |
| Supported Operating Systems | Linux, macOS, BSD, WSL |
| Installation Status | Installed by default |
| Category | Linux basic commands (tags: Linux basic commands (tags: join, combine, field, text)) |

## What is this command?

join merges lines from two files that share a key, similar to a database join. Both inputs must be sorted by the key for correct results.

-1 and -2 select the key field in each file, -t sets the separator and -a includes unmatched lines. For unsorted input, sort both files with a matching separator first.

## What problems does it solve?

- Combining two lists by user ID
- Merging two CSV files on a shared key
- Finding entries present in only one file
- Key-based merging that paste cannot do
## Key features

### Key-based merge

Merges lines that share a key.

- **When to use**: Linking two lists by ID
- **What you get**: Reproduces relational joins on flat files.
- **Limitations**: Unsorted keys produce wrong output.
### Field selection

-1 and -2 choose the key field per file.

- **When to use**: When the key is not the first column
- **What you get**: Join while keeping the original layout.
- **Limitations**: A wrong field index yields empty output.
### Including unmatched

-a1, -a2 and -v control unmatched lines.

- **When to use**: Auditing missing entries
- **What you get**: You can inspect set differences.
- **Limitations**: Empty fields require interpretation.
## Installation and usage

### Check whether it is installed

```
join --version
```

sudo apt install coreutils   # Debian/Ubuntu
sudo dnf install coreutils   # Fedora

## Real-world examples

### Basic join

Join on the first field.

```
sort users.txt -o u.txt
sort mail.txt -o m.txt
join u.txt m.txt
```

### Custom separator

Join comma-separated files.

```
sort -t, -k1,1 a.csv -o a.s
sort -t, -k1,1 b.csv -o b.s
join -t, a.s b.s
```

### Unmatched entries

Print keys only present on the left.

```
join -v1 u.txt m.txt | head
```

---
Source (HTML): https://games.aidebatehub.com/programs/linux/basics/join.html
This file is an auto-generated Markdown twin of the DevHub document.