# tar

Canonical URL: https://encode.wiki/codecs/data/tar/
Content version: ca42e61ede0a24f789d7287a0001244ad22f4abf
Status: current
License: CC BY-SA 4.0
Checksum (SHA-256): 5452489501a14d08ea6c9c662a16aba2a947c3cfa3c46fd94a15cea7f9fb6dac

tar ("tape archive") packs a directory tree into one stream, keeping names, permissions, owners, timestamps, symlinks and (optionally) ACLs and extended attributes. It does not compress; compression is a separate layer that tar runs for you, giving `.tar.gz`, `.tar.xz`, `.tar.zst` and so on. Combined with a good compressor, tar is the right tool for Unix backups and source distribution, and the compressor sees the whole archive as one stream, so it can exploit redundancy across files, unlike [ZIP](/codecs/data/zip/).

## Common commands

```sh
tar -cf archive.tar dir/               # create
tar -tf archive.tar                    # list
tar -xf archive.tar -C out/            # extract (into out/, which must exist)
tar -xf archive.tar path/in/archive    # extract one member
```

Reading is automatic: `tar -xf` detects gzip, xz, bzip2, zstd and others by content. For creating, pick the compressor by flag or suffix:

| Flag                     | Compression                                                 |
| ------------------------ | ----------------------------------------------------------- |
| `-z`                     | [gzip](/codecs/data/gzip/)                                  |
| `-J`                     | [xz](/codecs/data/xz/)                                      |
| `-j`                     | [bzip2](/codecs/data/bzip2/)                                |
| `--zstd`                 | [zstd](/codecs/data/zstd/)                                  |
| `-a` (`--auto-compress`) | chosen from the archive suffix: `tar -caf out.tar.zst dir/` |
| `-I 'prog args'`         | any program: `tar -I 'zstd -19 -T0' -cf out.tar.zst dir/`   |

Use `-I` for options such as threads and levels; `-I pigz` gives parallel gzip. For compressors tar does not know, such as brotli, pass `-I` for extraction as well: `tar -I brotli -xf out.tar.br`.

## Backups and restores

To preserve everything you will need on restore:

```sh
tar --xattrs --acls --numeric-owner -I 'zstd -T0' -cpf backup.tar.zst /path/to/dir
sudo tar --xattrs --acls --numeric-owner -xpf backup.tar.zst -C /restore
```

`-p` keeps permissions exactly (extraction as root does this by default). Owner restore only works as root, and `--numeric-owner` restores by UID/GID instead of names, which matters when restoring on a different system. `--one-file-system` stops tar crossing mount points, and `--exclude='pattern'` skips paths.

### Reproducible archives

Tar embeds timestamps, ordering and owner names. To get identical bytes from identical content:

```sh
tar --sort=name --mtime='2026-01-01 00:00Z' --owner=0 --group=0 --numeric-owner -cf - dir/ | zstd -T0 > dir.tar.zst
```

## Formats and tools

GNU tar writes the GNU format by default. `--format=pax` (POSIX.1-2001) supports long paths and sub-second times without the GNU extensions, and `--format=ustar` is the oldest and most limited. bsdtar (libarchive, the default on macOS and Windows) reads all of them. Because tar archives are a plain stream, there is no index: listing or extracting one file means reading through the archive, and a damaged stream loses everything after the damage unless the compressor limits it.

## Pitfalls

- **Absolute paths:** GNU tar strips the leading `/` on creation, so `tar -xf` will not overwrite system files. Use `-C /` for a full restore.
- **Compression flags and `-f`:** `-f` takes the next argument, so `tar -cfz out.tgz dir` creates a file named `z`. Put `-f` last (`-czf out.tgz`).
- **Symlinks and hard links** are stored as links; use `-h` to follow symlinks instead.