012/Archives & compression

See what is inside a tarball without extracting it

2026.08.31·003 min·macOS · Debian · Alpine · Shell

$ tar -tzvf archive.tar.gz

anatomy

tar

Tape archive. Bundles a directory tree into a single file, preserving permissions, ownership, and timestamps. Despite the name, it has not needed an actual tape drive since the 1980s.

-t

List the contents of the archive instead of extracting them. Nothing is written to disk.

-z

Filter through gzip. Tells tar the archive is compressed with gzip, so it decompresses on the fly while reading. Drop this flag for uncompressed .tar files, or swap it for -J (xz) or -j (bzip2).

-v

Verbose. Shows permissions, owner, group, size, and timestamp for each entry, not only the file path. Without it you get bare filenames.

-f

Read from a file. The next argument is the archive path. Without -f, tar reads from stdin, which is useful in a pipeline but confusing as a default.

Sample output

drwxr-xr-x  ada/staff         0 2026-08-28 14:32 project/
-rw-r--r--  ada/staff      1420 2026-08-28 14:30 project/package.json
-rw-r--r--  ada/staff       285 2026-08-28 14:30 project/tsconfig.json
drwxr-xr-x  ada/staff         0 2026-08-28 14:31 project/src/
-rw-r--r--  ada/staff      3874 2026-08-28 14:31 project/src/index.ts
-rw-r--r--  ada/staff      9216 2026-08-28 14:31 project/src/parser.ts
drwxr-xr-x  ada/staff         0 2026-08-28 14:32 project/dist/
-rw-r--r--  ada/staff     14208 2026-08-28 14:32 project/dist/index.js

Eight entries, rooted in a project/ directory. The sizes are in bytes, so parser.ts is about 9 KB and dist/index.js is 14 KB. If you expected the archive to contain a flat pile of files with no parent directory, you now know it is safe to extract without scattering files into your current directory.

When you would reach for it

Someone hands you a tarball and you want to know what is in it before you extract files into your working directory. You downloaded a release archive and want to confirm it has a top-level directory wrapping everything, not a loose collection of files. You are debugging a build pipeline that produces a tarball and you need to verify which files made it in and which were left out.

Gotchas

If the archive was created without a top-level directory, extracting it will scatter files directly into your current directory. Listing first with -t catches this. If you spot the problem, extract into a new directory: mkdir tmp && tar -xzvf archive.tar.gz -C tmp.
GNU tar auto-detects compression on extraction (tar -xf works regardless of format), but for listing with -t you still need the correct decompression flag (-z, -j, or -J), or use tar -tf and let GNU tar guess. BSD tar on macOS auto-detects for both -t and -x.
The verbose output format differs slightly between GNU tar and BSD tar. GNU tar shows user/group, BSD tar shows user group with spaces. The information is the same, the alignment is different.

Variants

$ tar -tzvf archive.tar.gz | grep '\.conf$'

Filter the listing to find specific files. Useful when the archive has hundreds of entries and you only care about config files

$ tar -tzvf archive.tar.gz | wc -l

Count how many files and directories are in the archive without scrolling through the full listing

$ curl -sL https://example.com/release.tar.gz | tar -tzvf -

List the contents of a remote tarball without downloading it to disk first. The -f - tells tar to read from stdin, and curl streams the data through the pipe

lineage

tar was written by John Gilmore for Version 7 Unix in 1979, replacing the older tp (tape archiver) command. The name stands for tape archive, reflecting an era when backup meant streaming files onto magnetic tape in sequence. Gilmore's implementation became the basis for the POSIX standard, but the format itself fractured early: BSD tar and System V tar diverged on header fields, leading to incompatibilities that persisted for years. The POSIX.1-1988 standard tried to unify them under the name ustar, and POSIX.1-2001 introduced the pax format to extend it further. GNU tar, maintained as part of the GNU project since the late 1980s, added its own extensions for long filenames, sparse files, and incremental backups. Today most systems ship GNU tar or a BSD-licensed reimplementation (libarchive's bsdtar, which Apple uses on macOS), and the flags for basic operations are the same across all of them.

> always look before you extract_