Linux command: tar

Almost everyone who uses Linux has typed tar -xzf something.tar.gz without being sure what the letters mean. That is a fair place to start, and it is where most people stop. The gap matters, because tar is the tool that packs up a website before a migration, that unpacks the software you download, and that produces the backup you will one day have to restore under pressure.

2. Where the Name Comes From

tar is short for tape archive.

tar  =  Tape ARchive

That is not a historical footnote. It is the single fact that explains almost every design decision in the tool, because a magnetic tape can only be read from beginning to end.

Nobody in this audience owns a tape drive, and the format is still shaped entirely around one. That is worth knowing, because it turns a list of quirks into a set of consequences.

The flags are also the subject of the best-known joke in Unix documentation: xkcd 1168, in which someone must extract a tar archive from memory within sixty seconds or the world ends. It is funny because the option letters really are hard to recall, and the reason is in section 3: they predate the conventions that would have made them memorable.

4. Simple Use Cases

4.1 The Three Commands You Actually Need

Start with a directory called site. These three commands cover most of daily use:

$ tar -czf site.tar.gz site/     # create, compressed with gzip
$ tar -tzf site.tar.gz           # list the contents
$ tar -xzf site.tar.gz           # extract into the current directory

Read the letters as a sentence and they stop being arbitrary: create zipped file, table of the zipped file, extract the zipped file. The f always comes last, because the archive name follows it.

GNU tar also accepts the flags with no dash at all, which is how most people learned it and why the flags look so strange in examples:

$ tar czf site.tar.gz site/     # identical to -czf, and much older syntax

This is a leftover from the original 1979 command, which had no concept of dashes. Both forms work; use whichever you find easier to remember.

4.2 What -f Really Does

The -f flag names the archive. Leave it out and tar falls back to its 1979 default, which is standard output, because that was where the tape drive lived. Modern GNU tar catches the obvious mistake:

$ tar cz site
tar: Refusing to write archive contents to terminal (missing -f option?)
tar: Error is not recoverable: exiting now

That protection only applies when the terminal is the destination. Redirect it and tar happily does what you asked, which is occasionally what you want:

$ tar cz site > site.tar.gz     # works, and is exactly what -f does
$ tar cf - site | ssh backup-server 'cat > site.tar'

The single dash in -f - means "use standard output", and it is the basis of every pipe in section 6.4.

One more error is worth recognising, because the wording is unhelpful the first time:

$ tar cf
tar: Old option 'f' requires an argument.

That means you wrote -f and then forgot to say which file.

4.3 Adding Compression

One letter selects the compressor. tar does not compress anything itself; it runs the external program and pipes through it.

Note that -j and -J differ only in case, and they are different compressors. That is a real source of confusion, and it is why the long forms are worth using in scripts.

You can also let tar work it out from the filename with -a (short for auto-compress):

$ tar caf backup.tar.xz site/    # picks xz because of the extension
$ tar caf backup.tar.zst site/   # picks zstd

$ file backup.tar.xz
backup.tar.xz: XZ compressed data, checksum CRC64

For extracting, none of this is necessary. Modern GNU tar detects the compression from the file itself, so tar xf handles every format above:

$ tar xf anything.tar.gz     # works
$ tar xf anything.tar.xz     # also works, no -J needed

The habit of typing xzf is harmless, but it is not required, and it fails you the day someone hands you a .tar.bz2.

The single letters give you each compressor at its default settings and nothing else. When you want a different level, or a compressor tar has no letter for, -I (long form --use-compress-program) takes an entire command:

$ tar -I 'zstd -19' -cf archive.tar.zst dir/    # maximum zstd compression
$ tar -I 'gzip -1'  -cf archive.tar.gz  dir/    # fastest gzip, for a big local copy
$ tar -I pigz       -cf archive.tar.gz  dir/    # parallel gzip, if installed

The quotes matter when the command has arguments. This is also the honest version of what -z has been doing all along: tar has always been running another program and piping through it.

4.4 Reading the Listing

Add -v (short for verbose) to -t and you get a listing that looks like ls -l, with one important difference:

$ tar -tvzf site.tar.gz
drwxrwxr-x peter/peter       0 2026-08-23 16:20 site/
drwxrwxr-x peter/peter       0 2026-08-23 16:20 site/logs/
-rw-rw-r-- peter/peter       9 2026-08-23 16:20 site/logs/error.log
-rw-rw-r-- peter/peter      14 2026-08-23 16:20 site/index.php
hrw-rw-r-- peter/peter       0 2026-08-23 16:20 site/hardlink.php link to site/index.php
drwxrwxr-x peter/peter       0 2026-08-23 16:20 site/images/
-rw-rw-r-- peter/peter  200000 2026-08-23 16:20 site/images/data.txt

The owner column is user/group rather than two separate columns, and those names are stored inside the archive. They are what the files were on the machine that created it, not what they will become on yours. Section 6.1 covers what actually happens on extraction.

Look at the fifth line. The type character is h, the size is 0, and the entry says link to site/index.php. tar noticed that two names pointed at the same file and stored the contents only once. This is one of the reasons a tar archive of a real system is often smaller than you expect, and one of the reasons it restores a system faithfully.

6. Advanced Use Cases

6.1 Permissions, Ownership and the umask

"Why did the permissions change when I extracted this?" is one of the most common tar questions, and the answer is a rule almost nobody is told.

When you extract as a normal user, tar applies your umask. Here are two files, one deliberately world-writable:

$ ls -l perm/
-rw-rw-rw- open.txt
-rw------- secret.txt

$ ( umask 077; tar xf perm.tar -C pout1 )
$ ls -l pout1/
-rw------- open.txt          <-- was 666, now 600
-rw------- secret.txt

The archive stored 666 faithfully. The umask removed the group and other bits on the way out. Add -p (short for preserve permissions) and the recorded mode wins:

$ ( umask 077; tar xpf perm.tar -C pout2 )
$ ls -l pout2/
-rw-rw-rw- open.txt          <-- preserved
-rw------- secret.txt

The manual records the other half of the rule: -p and --same-owner are the default for the superuser. So the same command produces different results depending on who runs it, which is exactly why a restore done with sudo behaves differently from one done in your own account.

Ownership works the same way. The archive stores names and numbers:

$ tar -tvf perm.tar
-rw------- peter/peter  0 2026-08-23 16:24 ./secret.txt

$ tar -tvf perm.tar --numeric-owner
-rw------- 1000/1000    0 2026-08-23 16:24 ./secret.txt

As a normal user you cannot give a file away, so everything you extract belongs to you regardless of what the archive says. As root, tar restores the recorded owner, and it matches by name first. That is usually right, and occasionally very wrong: if www-data is UID 33 on the old server and UID 82 on the new one, matching by name is what you want. If the accounts do not exist on the target at all, use --numeric-owner so the numbers are restored literally.

An archive records permissions and ownership; it does not enforce them. What you actually get on extraction depends on who is running tar and what their umask is.

For moving a website between servers, this is the difference between a working restore and an afternoon of chown:

$ sudo tar -xzpf site.tar.gz -C /var/www --numeric-owner

Beyond the classic Unix bits there is a second layer of metadata that a full system backup may depend on, and tar has switches for each part of it:

$ tar --help | grep -E 'acls|xattrs|selinux'
      --acls                 Enable the POSIX ACLs support
      --no-acls              Disable the POSIX ACLs support
      --no-selinux           Disable the SELinux context support
      --no-xattrs            Disable extended attributes support

Whether these are on by default depends on how your tar was built and on the filesystem underneath, which is why the help text lists both the enabling and the disabling form. For an ordinary website that stores nothing in extended attributes it makes no difference. For a system backup it matters, and the only way to know is to archive, restore into a scratch directory, and compare. Assume nothing here.

6.2 Symbolic Links, and the Flag That Doubles Your Backup

By default tar stores a symbolic link as a symbolic link. It records where the link points and nothing else, which is almost always what you want:

$ ls -l
current -> releases/2026-08

$ tar cf sym.tar current releases
$ tar tvf sym.tar
lrwxrwxrwx peter/peter  0 2026-08-23 16:32 current -> releases/2026-08
drwxrwxr-x peter/peter  0 2026-08-23 16:32 releases/
drwxrwxr-x peter/peter  0 2026-08-23 16:32 releases/2026-08/
-rw-rw-r-- peter/peter  8 2026-08-23 16:32 releases/2026-08/index.php

That is the standard deployment layout: a current symlink pointing at a dated release directory. The archive keeps the arrangement intact, and restoring it gives you the same structure back.

-h (long form --dereference) changes this. tar follows every link and archives what is on the other end:

$ tar chf symh.tar current releases
$ tar tvf symh.tar
drwxrwxr-x peter/peter  0 2026-08-23 16:32 current/
-rw-rw-r-- peter/peter  8 2026-08-23 16:32 current/index.php
drwxrwxr-x peter/peter  0 2026-08-23 16:32 releases/
drwxrwxr-x peter/peter  0 2026-08-23 16:32 releases/2026-08/
hrw-rw-r-- peter/peter  0 2026-08-23 16:32 releases/2026-08/index.php link to current/index.php

current is now a real directory holding a real copy. In this tiny example tar was clever enough to notice the duplication and store the second copy as a hard link, but that only works because both ends were inside the same archive.

The danger is the case where they are not. A symlink pointing outside the directory you are archiving turns into a full copy of whatever it points at:

$ ls -l /var/www/site/uploads
uploads -> /mnt/storage/media        # 40 GB of images on another volume

$ tar chzf site.tar.gz /var/www/site  # -h: now archiving 40 GB, not 200 MB

This is a genuinely common way for a backup to grow overnight for no visible reason. Use -h deliberately, when the archive must be self-contained and the reader will not have the link targets, and leave it off the rest of the time.

6.3 Sparse Files

A sparse file has a large logical size but does not use that much disk, because the filesystem records the empty regions as holes rather than storing zeros. Virtual machine disk images and some database files are the usual examples:

$ truncate -s 100M sparse.img
$ du -h --apparent-size sparse.img
100M
$ du -h sparse.img
0

One hundred megabytes of file, zero bytes on disk. tar does not know about the holes unless you tell it, and the difference is not subtle:

$ tar cf plain.tar sparse.img
$ ls -l plain.tar
104867840

$ tar cSf sparse.tar sparse.img       # -S, --sparse
$ ls -l sparse.tar
10240

Without -S, tar reads the holes as the zeros the filesystem reports and writes every one of them into the archive: 104 megabytes. With -S it records the holes as holes and the archive is ten kilobytes, a factor of ten thousand.

The cost is that -S makes tar examine every file for holes, which is wasted effort on a directory of ordinary web files. Turn it on when the archive contains disk images or database files, and leave it off otherwise. Compression hides some of this (a run of zeros compresses well) but not the time spent reading and writing them.

6.4 tar as a Pipe

Because tar reads and writes streams, it composes. -f - means standard input or output, and that single convention gives you three genuinely useful commands.

Copy a directory tree, preserving everything:

$ tar cf - source/ | tar xf - -C /destination

Two tars, one pipe, no temporary file. Unlike cp -r, this preserves hard links, sparse files and permissions exactly, because both ends speak the same format.

Move a tree to another machine, without storing it anywhere:

$ tar czf - /var/www/site | ssh user@newserver 'tar xzf - -C /var/www'

This is worth understanding properly, because it solves a real problem: you need no disk space for an intermediate archive on either side. The compression happens on the sending machine, so it also saves bandwidth. For a one-off migration of a website it is often faster and simpler than rsync, which is the better tool only when you will repeat the transfer.

Look inside an archive without unpacking it:

$ tar xzf backup.tar.gz -O var/www/site/configuration.php | grep password

All three follow from the same 1979 decision that the default output is a device rather than a file.

6.5 Formats, and the 100-Character Wall

The original 1979 header reserved exactly 100 bytes for the filename. That was generous for a system where paths were short, and it became a problem the moment directories got deeper. Three formats now exist, and GNU tar writes the third by default:

The limit is not theoretical. A 124-character filename is refused outright by ustar:

$ tar cf u.tar --format=ustar aaaa...124-characters...txt
tar: aaaa...: file name is too long (cannot be split); not dumped
tar: Exiting with failure status due to previous errors
$ echo $?
2

$ tar cf g.tar aaaa...124-characters...txt     # gnu, the default
$ echo $?
0

In practice you will never choose ustar. The choice worth making is pax for anything you intend to keep for years, because it is the actual standard and it stores timestamps at full precision rather than rounding to the second.

$ tar --format=pax -czf archive.tar.gz site/

6.6 Appending, and Why Never to a .tar.gz

Because an archive is a stream with an end marker, you can add to it by overwriting the marker. -r (short for append) does that:

$ tar cf plain.tar site/index.php
$ tar rf plain.tar site/logs/error.log
$ tar tf plain.tar
site/index.php
site/logs/error.log

-u (short for update) is the same thing but only adds files that are newer than the copy already in the archive. Neither removes anything: an "updated" file is appended, and the old version stays where it was. Repeated updates make an archive that grows forever and holds several versions of the same path, with tar extracting the last one it reads.

On a compressed archive, none of this works at all:

$ tar rf site.tar.gz site/logs
tar: Cannot update compressed archives
tar: Error is not recoverable: exiting now
$ echo $?
2

The reason is structural. gzip produces one continuous stream, so there is no way to find the end marker without decompressing everything, and no way to write past it without recompressing. If you need to add to a compressed archive, you decompress, append, and recompress. In practice you create a new archive instead.

There is also no delete. tar can never remove a member from an archive, on tape or on disk, for the same reason.

6.7 Incremental Backups

GNU tar can take a full backup and then archive only what changed. The state lives in a snapshot file given with -g:

$ tar czf full.tgz -g snapshot.snar data
$ tar tzf full.tgz
data/
data/one.txt

$ touch data/two.txt

$ tar czf incr.tgz -g snapshot.snar data
$ tar tzf incr.tgz
data/
data/two.txt

The second archive contains only the new file. The snapshot file is what makes it work, and it is also the weak point: lose it and tar has no idea what it already backed up, so the next run silently becomes a full backup again. Copy it alongside the archives.

Restoring means extracting the full archive and then each increment in order, which is exactly as fragile as it sounds. Incremental tar is worth knowing about; for anything important, a tool that tracks its own history, such as restic or borg, will hurt less.

6.8 Reproducible Archives

Pack the same files twice and you get two different archives. Nothing about the contents changed; the metadata did:

$ tar cf r1.tar d ; touch d/a.txt ; tar cf r2.tar d
$ sha256sum r1.tar r2.tar
4871b10e9a0df295ddd3da758d774ca9527b2381cb16ced15149230f9d0fe40f  r1.tar
c3e4021cbbf022087435c0c98e52fc37adebcbb1ca17537c0d714af92e404c25  r2.tar

Timestamps, ownership and the order in which the filesystem returned the directory entries all end up in the archive. Pin every one of them and the result becomes deterministic:

$ tar --sort=name --mtime='UTC 2026-01-01' --owner=0 --group=0 --numeric-owner -cf p1.tar d
$ touch d/a.txt d/b.txt
$ tar --sort=name --mtime='UTC 2026-01-01' --owner=0 --group=0 --numeric-owner -cf p2.tar d
$ cmp p1.tar p2.tar && echo IDENTICAL
IDENTICAL

The mtimes were deliberately changed between the two runs and the archives are still byte for byte the same. That turns "has anything actually changed since the last release?" into a checksum comparison instead of an argument.

Two details about --mtime. Write UTC in front of the date, or the stamp follows the timezone of whichever machine built the archive and two identical builds in different countries disagree. And keep the quotes: because the value contains a space, putting these flags in an unquoted shell variable splits them and tar reports 2026-01-01: Cannot stat: No such file or directory. If you want them in a variable, use --mtime=@0, which has no space in it.

One detail is worth knowing because it is the opposite of what people expect: tar czf is reproducible, but tar cf followed by gzip is not. gzip records the original filename and modification time in its header, and when it reads from a pipe there is neither to record:

$ hexdump -C reproducible.tar.gz | head -1
1f 8b 08 00 00 00 00 00  00 03 ...        <-- flags 00, timestamp all zeros

$ gzip -k plain.tar ; hexdump -C plain.tar.gz | head -1
1f 8b 08 08 a3 07 8b 6a  00 03 74 2e 74 61 72 00   |.......j..t.tar.|
                                                    <-- flag 08, a timestamp,
                                                        and the filename

Compressing a file on disk stores its name and the time; compressing a stream cannot. If you do build the archive in two steps, use gzip -n to leave both out.

6.9 Checking That the Archive Is Good

tar has three exit codes, and they are worth testing for in a script:

-d (short for diff, also --compare) checks an archive against the filesystem:

$ tar df cmp.tar
site/index.php: Mod time differs
site/index.php: Size differs
$ echo $?
1

Run immediately after creating an archive, this proves the archive matches what is on disk. It is not a substitute for a restore test, but it costs one command.

--totals prints what was written, which is a cheap sanity check in a backup script:

$ tar cf /dev/null --totals site
Total bytes written: 10240 (10KiB, 89MiB/s)

The value of that number is not the number itself but its stability. A nightly backup that has written about the same amount for months and suddenly writes a tenth of it is telling you something, and it is the only warning you are going to get.

Neither of those tells you whether the archive is still intact a month later on the disk you copied it to. For that, write a checksum next to it at the moment you create it:

$ sha256sum backup.tar.gz > backup.tar.gz.sha256

# before you rely on it, wherever it has ended up
$ sha256sum -c backup.tar.gz.sha256
backup.tar.gz: OK

A checksum answers exactly one question: are these the same bytes that were written? It says nothing about whether the right files went in. The three checks stack, cheapest first: tar tf archive > /dev/null proves the structure reads, the checksum proves the bytes survived, and an actual extraction into a scratch directory proves the backup is a backup. Only the last one is evidence.

8. Best Practices

• List before you extract. tar tzf archive.tar.gz | head costs a second and tells you whether the archive has a top-level directory, where the files will land, and whether it is what you think it is.
• Or just use --one-top-level. Unconditionally. It is harmless on well-made archives and it makes tarbombs impossible.
• Put --exclude before the paths. These options are positional. Modern tar warns and exits 2, but only if somebody reads the output.
• Use -C instead of cd. It works on both create and extract, it is explicit, and it keeps a backup script from depending on the directory it was started in.
• Do not fight the leading-slash message. Absolute paths are stripped for your safety. Create with -C /var/www site rather than naming the full path.
• Restore as root with -p and think about --numeric-owner. Permissions and ownership only survive if the person extracting has the right to set them, and account numbers rarely match between servers.
• Know what -h will pull in. Symlinks are stored as links by default, which is nearly always right. -h follows them, and a single link to another volume can multiply the size of a backup.
• Add -S when the archive contains disk images or database files. Without it a 100 MB sparse file becomes 100 MB of zeros in the archive instead of ten kilobytes.
• Pin the metadata for anything you release. --sort=name --mtime='UTC ...' --owner=0 --group=0 --numeric-owner makes the archive byte-identical between builds, so a checksum answers "did anything change?".
• Write a checksum next to the archive when you create it. sha256sum backup.tar.gz > backup.tar.gz.sha256 is the only way to know later that the bytes survived the copy.
• Unpack anything you did not create into a new empty directory, as yourself. Modern tar blocks the path-escape tricks, but nothing stops an archive from overwriting what is already in the directory you chose.
• Never append to a compressed archive. It cannot work. Create a new one.
• Choose the compressor deliberately. gzip when someone else must open it, xz when it will be downloaded many times, zstd when it runs nightly and you are the only consumer.
• Check the exit code in scripts. 0 is fine, 1 means something changed underneath you, 2 means the archive may be incomplete. A backup script that ignores this reports success either way.
• Dump the database separately. tar over a live database directory produces a file that looks like a backup and is not one.
• Test the restore, not the archive. tar df and --totals are cheap sanity checks; neither proves you can rebuild the site. Only extracting somewhere and looking does that.

$ man 1 tar               # the full manual, options grouped by mode
$ tar --help              # a much shorter summary
$ tar --show-defaults     # what your build assumes when you say nothing
$ info tar                # the GNU manual, far more detailed than the man page

10. Summary

tar is a program built for hardware nobody has used in decades, and it is still the right answer to "put this directory in one file" on every Unix system in the world.

• tar means tape archive. Almost every quirk in it follows from a tape being a stream you can only read start to finish.
• It concatenates; it does not compress. -z, -j, -J and --zstd pipe the result through a separate program, which is why the extension has two parts.
• Three modes, one of which you must pick: -c create, -t list, -x extract. -f names the archive, and without it tar writes to standard output.
• Extracting no longer needs a compression flag. tar xf works out the format itself.
• On real data, xz gave the best size and gzip the best compatibility, while zstd was fastest in both directions. bzip2 was beaten on every measure.
• -C chooses the directory on both create and extract; --strip-components removes the version-numbered wrapper directory that source releases use.
• --exclude is positional and must come before the paths, or it silently does nothing and tar exits 2.
• Absolute paths are stripped on purpose, so extraction always happens where you are.
• Permissions are recorded but filtered by your umask unless you pass -p, which is the default only for root. Ownership is matched by name.
• tar composes as a pipe: two tars copy a tree, and one over ssh moves a site without a temporary file anywhere.
• Symlinks are stored as links; -h follows them instead, which can quietly multiply the size of a backup.
• -S handles sparse files. Without it a 100 MB image with nothing in it writes 100 MB of zeros.
• Archives are not reproducible by default, but five flags make them byte-identical between builds.
• Modern GNU tar already blocks the classic extraction attacks. What it does not block is overwriting what is already in the directory you chose.
• A .tar.gz is a solid archive: smaller than a zip, but with no index, so extracting one file costs as much as extracting all of them.
• Look before you extract, or pass --one-top-level, and a tarbomb can never catch you.

This is the quick reference worth keeping:

tar czf out.tar.gz dir/        create, gzip
tar caf out.tar.xz dir/        create, compressor chosen by extension
tar tzf out.tar.gz             list (ALWAYS do this before extracting)
tar tvzf out.tar.gz            list with sizes, owners and modes
tar xf out.tar.gz              extract (format detected automatically)
tar xf out.tar.gz -C /target   extract somewhere else
tar xf out.tar.gz --one-top-level    never be tarbombed again

-c create   -t list   -x extract   -f FILE   -v verbose
-h follow symlinks (CHECK first)   -S sparse files (disk images)
-z gzip     -j bzip2  -J xz        --zstd    -a by extension
-C DIR      change directory (create AND extract)
-p          keep permissions exactly (default only for root)

--strip-components=1           drop the wrapper directory
--exclude='*.log'              BEFORE the paths, or it does nothing
--exclude-vcs                  drop .git, .svn and friends
--numeric-owner                restore UIDs, not names, across servers
--one-top-level                unpack into a directory named after the archive
--format=pax                   the standard format, for long-term archives
--exclude-from=list.txt        patterns from a file, kept in version control
-I 'zstd -19'                  any compressor, with its own options
-g snapshot.snar               incremental backup state

--sort=name --mtime='UTC 2026-01-01' --owner=0 --group=0 --numeric-owner
                               byte-identical archives between builds

tar cf - src | tar xf - -C dst          copy a tree, keeping hard links
tar czf - dir | ssh host 'tar xzf -'    move a site, no temp file
tar xzf a.tgz -O path/to/file           read one file out, without unpacking
tar df archive.tar                      compare archive against disk
tar tf archive.tar >/dev/null           cheap "is it corrupt" check
sha256sum a.tgz > a.tgz.sha256          prove the bytes survive the copy
tar tvf unknown.tgz | less              ALWAYS, before unpacking a stranger's

exit 0 ok | 1 files differ or changed while reading | 2 fatal

Backups and migrations are the two jobs where tar quietly does most of the work, and both are only as good as the restore nobody has tested. If you want the archives your server produces to be ones you can actually rebuild a website from, that is exactly the kind of quiet work I enjoy helping with.