← Full reference

tar

Packing directories into an archive and unpacking — .tar, .tar.gz, .tar.xz, listing and selective extraction

tar glues files and directories into a single archive, preserving the structure, permissions, owners and modification times. tar itself doesn't compress — compression is added with an option: z (gzip, .tar.gz/.tgz), J (xz, .tar.xz).

Syntax

tar -c [options] -f archive.tar files…     # create
tar -t [options] -f archive.tar [files…]   # list contents
tar -x [options] -f archive.tar [files…]   # extract

Exactly one mode is chosen. Options can be bundled: tar -czf = tar -c -z -f. The old form without a dash (tar czf) works too.

Modes

ModeWhat it does
-ccreate a new archive
-tlist the files in the archive
-xextract
-rappend files to the end of the archive (uncompressed .tar only)
-uappend files that are newer than their copies in the archive (.tar only)
-Aappend the contents of another .tar to the archive
--deletedelete files from the archive (.tar only)
-dcompare the archive with the files on disk: what differs

Archive and compression

OptionWhat it does
-f archivearchive file name; -f - — stdout/stdin
-zgzip (.tar.gz, .tgz)
-Jxz (.tar.xz) — stronger but slower
-j / --zstdbzip2 / zstd — need the programs of the same name on the system
-apick compression from the archive name's extension (when creating)
-I 'command'compress with any program: -I 'gzip -9', -I 'xz -T0'

When reading (-t, -x) you don't have to specify the compression: tar -xf archive.tar.xz detects it itself.

Which files to take

OptionWhat it does
-C directorychange to the directory before working: where to take files from or where to extract
--exclude='pattern'don't include matching files and directories at any level (put it before the file list)
--anchoredmatch the following --excludes against the start of the path in the archive
-X fileexclusion patterns from a file, one per line
--exclude-vcsdon't include .git, .svn and the like
-T listtake file names from a file (-T - — from stdin); with --null — separated by a null byte
--newer-mtime='2024-01-01'only files modified after the date (directories are always included)
-g snapshotincremental archive: next time, with the same snapshot, only changes are included
-hput the files that links point to into the archive, not the links themselves
--one-file-systemdon't cross into other file systems
--remove-filesdelete the source files after packing
-Pkeep absolute paths (leading /) — usually not needed

How to extract

OptionWhat it does
--strip-components=Ncut off the first N levels of the path
--transform='s,^app,app-1.0,'rename paths with a sed-like expression (works when creating too)
--wildcardsallow * patterns in names with -t/-x
-Oextract to stdout instead of disk
-kdon't overwrite existing files (an error for each)
--skip-old-filessilently skip existing files
--keep-newer-filesdon't overwrite files that are newer on disk
-mdon't restore the modification time — set the current one
-prestore permissions exactly, ignoring umask (on by default for root)
--no-same-ownerdon't restore owners — everything will belong to you

Owners in the archive and output

OptionWhat it does
-vprint file names; -vv or -tv — in detail
--owner=root --group=rootrecord a different owner in the archive
--numeric-ownerwrite and read owners as numbers only
--totalsprint how many bytes were written at the end
-Wverify the archive after creating it

A tar -tvf line: permissions, owner/group, size in bytes, modification date and time, path. For links — name -> target.

-rw-r--r-- alice/devs     2048 2024-05-01 12:00 app/config.yml

Examples

# pack a directory with gzip compression; paths in the archive start with app/
tar -czf app.tar.gz -C /srv app

# an archive with the date in its name
tar -czf "backup-$(date +%F).tar.gz" -C /srv app

# leave out the junk: exclusions go before the file list
tar -czf app.tar.gz --exclude=node_modules --exclude='*.log' --exclude-vcs -C /srv app

# view the contents without extracting (tar detects the compression itself)
tar -tf app.tar.gz
tar -tvf app.tar.gz

# extract into a given directory (it must exist)
mkdir -p /tmp/restore && tar -xzf app.tar.gz -C /tmp/restore

# extract without the archive's top-level directory
tar -xzf app.tar.gz -C /srv/app --strip-components=1

# extract one directory or files by pattern
tar -xzf app.tar.gz app/logs
tar -xzf app.tar.gz --wildcards '*.conf'

# print one file to the screen
tar -xOf app.tar.gz app/config.yml

# compare the archive with the files on disk
tar -df app.tar.gz -C /srv

# pack a list of files found by find
find /etc -name '*.conf' -mtime -7 -print0 | tar -czf recent-conf.tgz --null -T -

# a full backup and then only the changes
tar -czf full.tgz -g /var/backups/app.snar -C /srv app
tar -czf incr-1.tgz -g /var/backups/app.snar -C /srv app

# strong xz compression on all cores
tar -I 'xz -T0' -cf app.tar.xz -C /srv app

# archive through a pipe — e.g. straight to another machine
tar -czf - -C /srv app | ssh backup@example.com 'cat > app.tar.gz'

Pitfalls

  • -f must come last in a bundle. The archive name follows it: tar -cfz app.tar app creates an archive named z and tries to pack app.tar as a file.
  • Absolute paths. tar -czf a.tgz /srv/app strips the leading / and stores srv/app/… — on extraction you get ./srv/app. Use -C /srv app to get a short path in the archive.
  • --exclude after the file list has no effect. GNU tar warns ("has no effect") and packs everything; the archive is still created, but the exit code is non-zero.
  • --exclude isn't anchored to the start of the path. --exclude=cache excludes both app/cache and app/lib/cache — any path component with that name. To exclude only app/cache, add --anchored before --exclude=app/cache.
  • Patterns when extracting. tar -xf a.tar '*.log' without --wildcards looks for a file literally named *.log and reports "Not found in archive".
  • Extraction silently overwrites files. Look at the list first (-t), extract into an empty directory, or add -k / --skip-old-files.
  • A compressed archive can't be modified. -r, -u, -A, --delete work only on an uncompressed .tar: "Cannot update compressed archives".
  • An empty file list gives the error "Cowardly refusing to create an empty archive". This happens when find for -T found nothing.
  • Owners. When extracting, root restores the owners from the archive. A regular user gets all files owned by themselves.
  • bzip2 and zstd may be missing. tar -j and --zstd call external programs and fail with "not found" without them.

See also

gzip · rsync · find · split · ssh · date · checksums