{
  "schemaVersion": 1,
  "contentVersion": "ca42e61ede0a24f789d7287a0001244ad22f4abf",
  "id": "docs/codecs/data/tar",
  "collection": "docs",
  "title": "tar",
  "description": "tar bundles files and their Unix metadata into one stream, which you then compress with gzip, xz, zstd or another tool; this page covers the commands and flags that matter.",
  "canonicalUrl": "https://encode.wiki/codecs/data/tar/",
  "apiUrl": "https://encode.wiki/api/v1/documents/docs/codecs/data/tar.json",
  "markdownUrl": "https://encode.wiki/api/v1/markdown/docs/codecs/data/tar.md",
  "status": "current",
  "tags": [
    "migrated"
  ],
  "license": "CC BY-SA 4.0",
  "dates": {
    "lastVerified": "2026-10-08T00:00:00.000Z"
  },
  "authors": [],
  "sources": [
    {
      "title": "GNU tar manual",
      "url": "https://www.gnu.org/software/tar/manual/tar.html",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    },
    {
      "title": "POSIX pax utility and formats",
      "url": "https://pubs.opengroup.org/onlinepubs/9799919799/utilities/pax.html",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    }
  ],
  "provenance": {
    "originUrl": "https://github.com/av1-community-contributors/codec-wiki/blob/37c3317fd058b23c71a87679bed5619a98f77752/docs/data/tar.mdx",
    "originCommit": "37c3317fd058b23c71a87679bed5619a98f77752",
    "migratedAt": "2026-08-21T00:00:00.000Z",
    "modified": true,
    "originPath": "docs/data/tar.mdx"
  },
  "headings": [
    {
      "depth": 2,
      "text": "Common commands",
      "anchor": "common-commands"
    },
    {
      "depth": 2,
      "text": "Backups and restores",
      "anchor": "backups-and-restores"
    },
    {
      "depth": 3,
      "text": "Reproducible archives",
      "anchor": "reproducible-archives"
    },
    {
      "depth": 2,
      "text": "Formats and tools",
      "anchor": "formats-and-tools"
    },
    {
      "depth": 2,
      "text": "Pitfalls",
      "anchor": "pitfalls"
    }
  ],
  "sections": [
    {
      "id": "_preamble",
      "title": "Page introduction",
      "depth": 0,
      "canonicalUrl": "https://encode.wiki/codecs/data/tar/",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/_preamble.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/_preamble.md",
      "checksum": "db21d640a9167c05bb84bc858a772d114312a27fc0fac4a57993311ffb7f3ad6",
      "bytes": 523
    },
    {
      "id": "common-commands",
      "title": "Common commands",
      "depth": 2,
      "anchor": "common-commands",
      "canonicalUrl": "https://encode.wiki/codecs/data/tar/#common-commands",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/common-commands.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/common-commands.md",
      "checksum": "fb77909bf4f7832ac368aacf503b8486e7095457c62b87fa8212701d04dd57af",
      "bytes": 1329
    },
    {
      "id": "backups-and-restores",
      "title": "Backups and restores",
      "depth": 2,
      "anchor": "backups-and-restores",
      "canonicalUrl": "https://encode.wiki/codecs/data/tar/#backups-and-restores",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/backups-and-restores.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/backups-and-restores.md",
      "checksum": "8dbb9ac8996f33749462490055e8d21ca6aa6b91717741ef85f8c40189e53195",
      "bytes": 805
    },
    {
      "id": "reproducible-archives",
      "title": "Reproducible archives",
      "depth": 3,
      "anchor": "reproducible-archives",
      "canonicalUrl": "https://encode.wiki/codecs/data/tar/#reproducible-archives",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/reproducible-archives.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/reproducible-archives.md",
      "checksum": "5a3d641e866e8731390baf1d8bde7f957619cef6729b2e213c3bc2e834f21d0e",
      "bytes": 250
    },
    {
      "id": "formats-and-tools",
      "title": "Formats and tools",
      "depth": 2,
      "anchor": "formats-and-tools",
      "canonicalUrl": "https://encode.wiki/codecs/data/tar/#formats-and-tools",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/formats-and-tools.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/formats-and-tools.md",
      "checksum": "75071cad3ed074c21904cdec46e58b8857c9b1176f73195a69cba28243ee3518",
      "bytes": 503
    },
    {
      "id": "pitfalls",
      "title": "Pitfalls",
      "depth": 2,
      "anchor": "pitfalls",
      "canonicalUrl": "https://encode.wiki/codecs/data/tar/#pitfalls",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/pitfalls.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/codecs/data/tar/pitfalls.md",
      "checksum": "6f78874ed167db17f2ee373f1ccae680420a68e29f5be0c1df1df984d782c8d4",
      "bytes": 392
    }
  ],
  "outboundReferences": [
    "/codecs/data/bzip2/",
    "/codecs/data/gzip/",
    "/codecs/data/xz/",
    "/codecs/data/zip/",
    "/codecs/data/zstd/"
  ],
  "checksum": "5452489501a14d08ea6c9c662a16aba2a947c3cfa3c46fd94a15cea7f9fb6dac",
  "contentFormat": "markdown",
  "markdown": "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/).\n\n## Common commands\n\n```sh\ntar -cf archive.tar dir/               # create\ntar -tf archive.tar                    # list\ntar -xf archive.tar -C out/            # extract (into out/, which must exist)\ntar -xf archive.tar path/in/archive    # extract one member\n```\n\nReading is automatic: `tar -xf` detects gzip, xz, bzip2, zstd and others by content. For creating, pick the compressor by flag or suffix:\n\n| Flag                     | Compression                                                 |\n| ------------------------ | ----------------------------------------------------------- |\n| `-z`                     | [gzip](/codecs/data/gzip/)                                  |\n| `-J`                     | [xz](/codecs/data/xz/)                                      |\n| `-j`                     | [bzip2](/codecs/data/bzip2/)                                |\n| `--zstd`                 | [zstd](/codecs/data/zstd/)                                  |\n| `-a` (`--auto-compress`) | chosen from the archive suffix: `tar -caf out.tar.zst dir/` |\n| `-I 'prog args'`         | any program: `tar -I 'zstd -19 -T0' -cf out.tar.zst dir/`   |\n\nUse `-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`.\n\n## Backups and restores\n\nTo preserve everything you will need on restore:\n\n```sh\ntar --xattrs --acls --numeric-owner -I 'zstd -T0' -cpf backup.tar.zst /path/to/dir\nsudo tar --xattrs --acls --numeric-owner -xpf backup.tar.zst -C /restore\n```\n\n`-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.\n\n### Reproducible archives\n\nTar embeds timestamps, ordering and owner names. To get identical bytes from identical content:\n\n```sh\ntar --sort=name --mtime='2026-01-01 00:00Z' --owner=0 --group=0 --numeric-owner -cf - dir/ | zstd -T0 > dir.tar.zst\n```\n\n## Formats and tools\n\nGNU 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.\n\n## Pitfalls\n\n- **Absolute paths:** GNU tar strips the leading `/` on creation, so `tar -xf` will not overwrite system files. Use `-C /` for a full restore.\n- **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`).\n- **Symlinks and hard links** are stored as links; use `-h` to follow symlinks instead.\n"
}