Linux tar command

Updated: 11/06/2021 by Computer Hope
tar command

On Unix-like operating systems, the tar command creates, maintains, modifies, and extracts files that are archived in the tar format.

This page covers the GNU/Linux version of tar.

Description

"Tar" stands for tape archive. It is an archiving file format.

tar was originally developed in the early days of Unix for the purpose of backing up files to tape-based storage devices. It was later formalized as part of the POSIX standard, and today is used to collect, distribute, and archive files, while preserving file system attributes such as user and group permissions, access and modification dates, and directory structures.

This documentation covers the GNU version of tar, which is included with most modern variants of the Linux operating system.

Syntax

tar [-] A --catenate --concatenate | c --create | d --diff --compare | 
    --delete | r --append | t --list | --test-label | u --update | 
    x --extract --get [options] [pathname ...]

Operation

The first argument to tar should be a function specification: either one of the letters A, c, d, r, t, u, or x, or one of the long function names. A function letter does not need to be prefixed with a dash ("-"), and may be combined with other single-letter options. A long function name must be prefixed with a double dash ("--"). Some options take a parameter; with the single-letter form these must be given as separate arguments. With the long form, they may be given by appending "=value" to the option.

For example, the following commands are all equivalent:

tar --create --file=archive.tar file1 file2
tar -c -f archive.tar file1 file2
tar -cf archive.tar file1 file2
tar cf archive.tar file1 file2

Functions

Specifying one of the following functions selects what tar's main mode of operation will be:

A, --catenate,
--concatenate
Append tar files to an archive.
c, --create Create a new archive.
d, --diff, --compare Calculate any differences between the archive and the file system.
--delete Delete from the archive. (This function doesn't work on magnetic tapes).
r, --append Append files to the end of a tar archive.
t, --list List the contents of an archive.
--test-label Test the archive label, and exit.
u, --update Append files, but only those that are newer than the copy in the archive.
x, --extract, --get Extract files from an archive.

Other options

The following options specify the way tar operates:

-[0-7][lmh] Specifies drive and density. (If you're not sure what this means, you don't need to use this option.)
-a, --auto-compress Use the archive's suffix to determine the compression program. For example, if this option is specified, an archive with the extension .tar.gz is always handled as if the --gzip option had been specified (see --gzip, below).
--add-file=file Add file to the archive. (This option is especially useful when the name of the file begins with a dash.)
--anchored File name patterns must match from the beginning of a file name.
--no-anchored File name patterns may match after any "/" (this is the default for excluding files; see --exclude, below).
--atime-preserve Preserve access times on archived files, either by restoring the times, or (if the operating system supports it) not changing them in the first place.
--no-auto-compress Do not automatically determine the compression program using the archive file name suffix.
-b,
--blocking-factor BLOCKS
Use BLOCKS x 512 bytes-per-record when handling the archive.
-B, --read-full-records "Re-block" all input. This option helps read damaged archives.
--backup[=backup-method Rather than deleting files from the file system, tar will back them up using the specified backup method backup-method, which may be one of the following:

t, numbered Always make numbered backups.
nil, existing Make numbered backups of files that already have them, and simple backups of the others.
never, simple Always make simple backups.

If not specified, backup-method defaults to the value of environment variable VERSION_CONTROL; if VERSION_CONTROL is undefined, backup-method defaults to existing.
-C, --directory DIR Change to directory DIR before performing any operations.
--check-device Check device numbers when creating incremental archives. This is the default behavior.
--no-check-device Do not check device numbers when creating incremental archives.
--checkpoint[=NUMBER] Use "checkpoints": display a progress message every NUMBER records (default 10).
--checkpoint-action=ACTION Execute ACTION at every checkpoint. ACTION may be one of the following:

bell Play an audible bell at the console.
dot, . Print a single dot.
echo Display a text message at the console (to standard error).
echo=string Display string string on standard error; before output, any metacharacters in string are expanded.
exec=command Execute the given command.
sleep=time Wait for time seconds.
ttyout=string Output string on the current console ('/dev/tty').
Several --checkpoint-action options can be specified. The supplied actions will be executed in the order of their appearance on the command line.

Using --checkpoint-action without --checkpoint will assume the default checkpoint interval of 10 records.
--delay-directory-restore Delay setting modification times and permissions of extracted directories until extraction has ended.
--no-delay-directory-restore Modification times and permissions of extracted directories are set when all files from this directory are extracted. This is the default.
--exclude=PATTERN Avoid operating on files whose names match file name pattern PATTERN.
--exclude-backups Exclude backup and lock files from all operations.
--exclude-caches Causes tar to exclude all directories that contain a cache directory tag.

A cache directory tag is a short file with the name CACHEDIR.TAG and having a standard header specified in https://bford.info/cachedir/. This option excludes the contents of the directory, but archives the directory itself and the CACHEDIR.TAG file.
--exclude-caches-all Omit directories containing a CACHEDIR.TAG file entirely.
--exclude-caches-under Exclude everything under directories containing a CACHEDIR.TAG file, including the CACHEDIR.TAG file; but, archive the directory.
--exclude-tag=FILE Exclude the contents of any directory containing file FILE, but archive the directory and the file FILE.
--exclude-tag-all=FILE Omit directories containing file FILE entirely.
--exclude-tag-under=FILE Exclude everything under directories containing file FILE including the file FILE; but, archive the directory.
--exclude-vcs Exclude version control subdirectories. This option recognizes the files and directories used by many widely-used VCS systems. The files excluded are:

  • CVS/, and everything under it
  • RCS/, and everything under it
  • SCCS/, and everything under it
  • .git/, and everything under it
  • .gitignore
  • .cvsignore
  • .svn/, and everything under it
  • .arch-ids/, and everything under it
  • {arch}/, and everything under it
  • =RELEASE-ID
  • =meta-update
  • =update
  • .bzr
  • .bzrignore
  • .bzrtags
  • .hg
  • .hgignore
  • .hgrags
  • _darcs
-f, --file=ARCHIVE Use archive file (or device) ARCHIVE.
-F, --info-script,
--new-volume-script=NAME
Run script NAME at the end of each tape (implies -M).
--force-local Force tar to treat the archive file as a local file, even if its name contains a colon.
--full-time Print the full resolution of all file times.
-g, --listed-incremental=FILE During a --create operation, this option specifies that the archive be a new GNU-format incremental backup, using snapshot file FILE to determine which files to backup. With other operations, this option informs tar that the archive is in incremental format.
-G, --incremental Handle old GNU-format incremental backups.
--group=NAME Force NAME as group for added files.
-h, --dereference Follow symlinks; archive the files they point to.
-H, --format=FORMAT Create archive of the given format, where FORMAT is one of the following:

gnu GNU tar 1.13.x format.
oldgnu GNU format used in tar versions 1.12 and lower.
pax POSIX 1003.1-2001 ("pax") format.
posix Same as pax.
ustar POSIX 1003.1-1988 ("ustar") format.
v7 Old Unix version 7 tar format.
--hard-dereference Follow hard links; archive the files they refer to.
-i, --ignore-zeros Ignore zeroed blocks in archive. Normally an entire block of bytes with a value of zero indicates an end-of-archive; this option helps tar handle a damaged archive, or any other oddly-formed archive with blocks of zeros in its contents.
-I,
--use-compress-program=PROG
Use external compression program PROG. Use this option if you are not happy with the compression program associated with the suffix at compile time, or if you have a compression program that GNU tar does not support. The PROG argument must be a valid command, as you would type it at the command-line prompt, with any additional options as needed. Enclose it in quotes if it contains white space.

PROG should follow two conventions: First, when invoked without additional options, it should read data from standard input, compress it and output it on standard output. Secondly, if invoked with the additional '-d' option, it should do exactly the opposite: read the compressed data from the standard input and produce uncompressed data on the standard output.

The latter requirement means you must not use the '-d' option as a part of the PROG command invocation itself.
--ignore-case Ignore character case when matching patterns or file names.
--no-ignore-case Use case-sensitive pattern and file name matching (this is the default).
--ignore-command-error Ignore exit codes of subprocesses.
--no-ignore-command-error Treat non-zero exit codes of subprocesses as an error.
--ignore-failed-read Do not exit merely because an unreadable file was encountered.
--index-file=FILE Send verbose output to file FILE for later use.
-j, --bzip2 This option tells tar to read or write archives using the bzip2 compressor.
-J, --xz Tells tar to read or write archives using the xz compressor.
-k, --keep-old-files Do not overwrite existing files when extracting files from an archive, and return an error if such files exist.
-K, --starting-file=NAME This option affects extraction only; tar skips extracting files in the archive until it finds one that matches name.
--keep-newer-files Don't replace existing files that are newer than their archive copies.
-l, --check-links Check the number of links dumped for each processed file. If this number does not match the total number of hard links for the file, print a warning message.
-L, --tape-length=size[suf] Change tape after writing a certain number of bytes. If suf is not specified, SIZE is treated as kilobytes (1024 bytes), which is equivalent to specifying suf as B. suf may be one of the following:

suffix units byte equivalent
b Blocks size x 512
B Kilobytes size x 1024
c Bytes size
G Gigabytes size x 1024^3
K Kilobytes size x 1024
k Kilobytes size x 1024
M Megabytes size x 1024^2
P Petabytes size x 1024^5
T Terabytes size x 1024^4
w Words size x 2
--level=n When using the --listed-incremental option, force an incremental backup of level n.
--lzip Read or write archives through the lzip compressor.
--lzma Read or write archives through the lzma compressor.
--lzop Read or write archives through the lzop compressor.
-m, --touch Sets the data modification time of extracted files to the extraction time, rather than the data modification time stored in the archive. In other words, touch all extracted files.
-M, --multi-volume Create, list, or extract a multi-volume archive. Such archives are broken into parts so that they may fit on media too small to contain the entire archive.
--mode=permissions When adding files to an archive, tar assigns permissions to the archive members, rather than the permissions from the files. The permissions can be specified either as an octal number or as symbolic permissions, as with chmod.
--mtime=date When adding files to an archive, tar uses date as the modification time of members when creating archives, instead of their actual modification times. The value of date can be either a textual date representation or a name of the existing file, starting with "/" or ".", in which case the modification time of that file is used.
-n, --seek Assume that the archive media supports seeking to arbitrary locations. Usually, tar determines automatically whether the archive can be seeked or not; this option is intended for use in cases when such recognition fails. It takes effect only if the archive is open for reading with "--list" or "--extract" options).
-N, --newer, --after-date=date Only store files whose data or status has changed on or after date. If date is a file name, the date of that file is used.
--newer-mtime=date Like --after-time, but looks at modification times only.
--null When tar uses the '--files-from' option, this option instructs tar to expect file names terminated with NUL, so tar can correctly work with file names that contain newlines.
--no-null Cancels any previous --null option specified.
--numeric-owner Always use numeric IDs, rather than names, for user/group ownership information.
-O, --to-stdout Extract files to standard output.
--occurrence[=number] This option can be used in conjunction with one of the subcommands "--delete", "--diff", "--extract" or "--list" when a list of files is given either on the command-line or via '-T' option.

This option instructs tar to process only the numberth occurrence of each named file. The number defaults to 1, so:

tar -x -f archive.tar --occurrence filename
will extract the first occurrence of the member "filename" from "archive.tar" and will terminate without scanning to the end of the archive.
--old-archive, --portability Same as "--format=v7".
--one-file-system Prevents tar from crossing file system boundaries when archiving. Can be used with any write operation.
--overwrite Overwrite existing files when extracting.
--overwrite-dir Overwrite metadata of existing directories when extracting (this is the default behavior).
--no-overwrite-dir Preserve metadata of existing directories when extracting.
--owner=user Specifies that tar should use user as the owner of members when creating archives, instead of the user associated with the source file. The user is a username, or a user's numeric ID, or both as "name:id".
-p, --preserve-permissions,
--same-permissions
When tar is extracting an archive, it normally subtracts the user's umask from the permissions specified in the archive and uses that number as the permissions to create the destination file. Specifying this option instructs tar that it should use the permissions directly from the archive.
-P, --absolute-names Don't strip leading "/"s from file names.
--pax-option=keyword-list Enables creation of the archive in POSIX.1-2001 format, where keyword-list is a comma-separated list of keyword options specific to that format.
--posix Same as --format=posix.
--preserve This is the same as specifying both "--preserve-permissions" and "--same-order".
--quote-chars=STRING When displaying files and other members of an archive, tar treats file names in a special way to avoid ambiguities caused by certain characters that may occur in the file name; this is called name quoting. The --quote-chars option will, additionally, quote any characters occurring in STRING.
--no-quote-chars=STRING When name quoting, tar never quotes any of the characters in STRING.
--quoting-style=STYLE When name quoting, use name quoting style STYLE. Valid values of STYLE are: literal, shell, shell-always, c, escape, locale, and clocale. The default quoting style is escape, unless overridden while configuring the package.
-R, --block-number With this option specified, tar prints error messages for read errors with the block number in the archive file.
--record-size=siz[suf] Instructs tar to use size bytes-per-record when accessing the archive. The argument can be suffixed with a size suffix, e.g., "--record-size=10K" for 10 kilobytes.
--recursion Recurse into directories (this is the default).
--no-recursion Do not recurse into subdirectories when archiving.
--recursive-unlink Remove existing directory hierarchies before extracting directories of the same name from the archive.
--remove-files Remove files after adding them to an archive.
--restrict Disable use of some potentially harmful tar options. Currently this option disables shell invocation.
--rmt-command=cmd In cases where tar uses a remote tape server, this option notifies tar that it should use cmd as the remote tape server program instead of the default, "/usr/libexec/rmt".
--rsh-command=cmd In cases where tar uses a remote shell to communicate with non-local devices, this option notifies tar that it should use cmd instead of the default, rsh.
-s, --preserve-order,
--same-order
This option helps when processing large lists of file names on machines with small amounts of memory. It is used in conjunction with --compare, --list or --extract.

The --same-order option tells tar that the list of file names to be listed or extracted is sorted in the same order as the files in the archive. This allows a large list of names to be used, even on a small machine that would not otherwise be able to hold all the names in memory at the same time. Such a sorted list can easily be created by running tar -t on the archive and editing its output.

This option is probably never needed on modern computer systems.
-S, --sparse This option instructs tar to test each file for sparseness before attempting to archive it. If the file is sparse it is treated specially, thus allowing to decrease the amount of space used by its image in the archive.

This option is meaningful only when creating or updating archives. It has no effect on extraction.
--same-owner Attempt to give extracted files the same ownership as exists in the archive (this is the default for superuser).
--no-same-owner Do not attempt to restore ownership when extracting. This is the default behavior for ordinary users, so this option has an effect only for the superuser.
--no-same-permissions Apply the user's umask when extracting permissions from the archive. This is the default behavior for ordinary users.
--no-seek Do not attempt to seek to arbitrary locations within an archive.
--show-defaults Display tar's default options. This can be useful in certain shell scripts.
--show-omitted-dirs When listing or extracting, list each directory that does not match search criteria.
--show-transformed-names,
--show-stored-names
Display file or member names after applying any name transformations. In particular, when used in conjunction with one of the archive creation operations it instructs tar to list the member names stored in the archive, instead of the actual file names.
--sparse-version=version-number Specifies the format version to use when archiving sparse files. Implies '--sparse'.
--strip-components=number Strip given number of leading components from file names before extraction. For example, if archive "archive.tar" contained a member named "/some/file/name", then running:

tar --extract --file archive.tar --strip-components=2
would extract this file to file "name".
--suffix=suffix Uses the file name suffix suffix when backing up files. If --suffix is not specified, the default backup suffix is the value of the environment variable DEFAULT_BACKUP_SUFFIX, or if that variable is not defined, "~".
-T, --files-from=file tar uses the contents of file as a list of archive members or files to operate on, in addition to those specified on the command line.
--to-command=command During extraction, tar will pipe extracted files to the standard input of command.
--totals[=signum] Display byte totals when processing an archive. If signum is specified, these totals are displayed when tar receives signal number signum.
--transform, --xform=sed-expr Replace file names with sed replacement expression sed-expr. For example,

tar cf archive.tar --transform 's,^\./,usr/,'
adds to archive.tar files from the current working directory, replacing initial "./" prefix with "usr/".
-U, --unlink-first Remove a corresponding file from the file system before extracting it from the archive, rather than overwriting it.
--unquote Unquote file names read in with -T; this is the default.
--no-unquote Do not unquote file names read in with -T.
--utc Print all file times in UTC (universal time).
-v, --verbose Operate verbosely.
-V, --label=name When creating an archive, write name as a name record in the archive. When extracting or listing archives, tar only operates on archives with a label matching the pattern specified in name.
--volno-file=file Used in conjunction with "--multi-volume", tar will keep track of which volume of a multi-volume archive it's working on in file file.
-w, --interactive, --confirmation Ask for confirmation for every action.
-W, --verify Attempt to verify the archive after writing it.
--warning=keyword Control display of the warning messages identified by keyword. If keyword starts with the prefix "no-", such messages are suppressed. Otherwise, they are enabled.

Multiple "--warning" specifications may be used.

There are keywords for various warning messages available in tar. The two global keywords are:


all Enable all warning messages. This is the default.
none Disable all warning messages.
--wildcards Use wildcards.
--wildcards-match-slash When this option is specified, a wildcard like "*" in the pattern can match a "/" in the name. Otherwise, "/" is matched only by "/". This is the default when tar is excluding files.
--no-wildcards-match-slash "/" cannot be matched by a wildcard, only by "/".
--no-wildcards Wildcards are not permitted. File names may only be matched verbatim.
-X, --exclude-from=file Like --exclude, but excludes files matching the patterns listed in the file file.
-z, --gzip, --gunzip This option tells tar to read or write archives through gzip, allowing tar to directly operate on several kinds of compressed archives transparently. This option should be used, for example, when operating on files with the extension .tar.gz.
-Z, --compress, --uncompress tar uses the compress program when operating on files.

Environment

The following environment variables affect the operation of tar:

SIMPLE_BACKUP_SUFFIX File name suffix to use when backing up files, if --suffix is not specified. The default backup suffix is "~".
TAR_OPTIONS Any options specified in this variable will be prepended to options specified to tar on the command line.
TAPE The archiving tape or file to use if --file is not specified. If this variable is not defined, and no --file is specified, tar uses standard input and standard output instead.

Examples

tar -cf archive.tar file1 file2

Create archive archive.tar containing files file1 and file2. Here, the c tells tar you will be creating an archive; the f tells tar that the next option (here it's archive.tar) will be the name of the archive it creates. file1 and file2, the final arguments, are the files to be archived.

tar -tvf archive.tar

List the files in the archive archive.tar verbosely. Here, the t tells tar to list the contents of an archive; v tells tar to operate verbosely; and f indicates that the next argument will be the name of the archive file to operate on.

tar -xf archive.tar

Extract the files from archive archive.tar. x tells tar to extract files from an archive; f tells tar that the next argument will be the name of the archive to operate on.

tar -xzvf archive.tar.gz

Extract the files from gzipped archive archive.tar.gz verbosely. Here, the z tells tar that the archive will be compressed with gzip.

tar -cf archive.tar mydir/

Creates an archive of the directory mydir.

tar -czf archive.tar.gz mydir/

Creates an gzip-compressed archive of the directory mydir.

tar -zxvf myfile.tar.gz

Extract the contents of the myfile.tar.gz into the current directory.

tar -xvf archive.tar documents/work/budget.doc

Extract only the file documents/work/budget.doc from the archive archive.tar. Produce verbose output.

tar -xvf archive.tar documents/work/

Extract only the directory documents/work/, and any files it contains, from the archive archive.tar. Produce verbose output.

tar -xvf archive.tar --wildcards '*.doc'

Extract only files with the extension .doc from the archive archive.tar. The --wildcards option tells tar to interpret wildcards in the name of the files to be extracted; the file name (*.doc) is enclosed in single-quotes to protect the wildcard (*) from being expanded incorrectly by the shell.

tar -rvf archive.tar documents/work/budget.doc

Add the file documents/work/budget.doc to the existing archive archive.tar. The r option is the same as the long option --append.

tar -uvf archive.tar documents/work/budget.doc

Add the file documents/work/budget.doc to the archive archive.tar only if it's newer than the version already in the archive (or does not yet exist in the archive). Here, u is the same as the long option --update.

tar -cf - documents/work/ | wc -c

Estimate the file size of an archive of the directory documents/work, but do not create the file. Here, the archive file is specified as a dash ("-"), which tells tar to send its archived output to the standard output rather than a file on disk. This output is then piped to the wc command, which reports how many bytes (-c) were in the input it received.

tar -czf DogPhotos.tar.gz --exclude='kitty.jpg' MyPetPhotos

Create DogPhotos.tar.gz of all files contained in the MyPetPhotos without the kitty.jpg photo.

tar tf hope.tar.gz | grep myfile.txt

Search the hope.tar.gz file for the file myfile.txt and list the full path of the file. The returned results would resemble the line shown below.

computerhopehope/homedir/public_html/data/myfile.txt

tar -zxvf hope.tar.gz computerhopehope/homedir/public_html/data/myfile.txt

In the above example, the tar command would extract the one file myfile.txt from the hope.tar.gz. The full path to this file was determined using the example shown earlier.

ar — Create, modify, and extract files from archives.
basename — Strip directory information and suffixes from file names.
cd — Change the working directory.
chown — Change the ownership of files or directories.
cpio — Copy files to or from archives.
dirname — Strip the file name from a pathname, leaving only the directory component.
gzip —Create, modify, list the contents of, and extract files from GNU zip archives.
ls — List the contents of a directory or directories.
mt — Control magnetic tapes.
zcat — Print the uncompressed contents of compressed files.