Linux and Unix tar command

Quick links

About tar
Syntax
Examples
Related commands
Linux and Unix main page

About tar

The tar program is used to create, maintain, modify, and extract files that are archived in the tar format.

Syntax

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

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.

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 will always be 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 Filename patterns must match from the begining of a file name.
--no-anchored Filename 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 sypports it) not changing them in the first place.
--no-auto-compress Do not automatically determine the compression program using the archive filename 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 can help 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 the end of extraction.
--no-delay-directory-restore Modification times and permissions of extracted directories are set when all files from this directory have been extracted. This is the default.
--exclude=PATTERN Avoid operating on files whose names match filename 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 http://www.brynosaurus.com/cachedir/spec.html. 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 VCSs. 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 that 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 filename 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 will skip 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 a number of 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 will assign permissions to the archive members, rather than the permissions from the files. 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 will use 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 filename, the date of that file is used.
--newer-mtime=date Like --after-time, but looks at modification times only.
--null When tar is using 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 numberic 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. 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. user can be 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 filename; 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 will never quote 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 is using 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 is using 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 found to be 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, as opposed to 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 filename 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 will use 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 filenames with sed replacement expression sed-expr. For example,

tar cf archive.tar --transform 's,^\./,usr/,'
will add 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 simply overwriting it.
--unquote Unquote filenames read in with -T; this is the default.
--no-unquote Do not unquote filenames 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 will only operate on archives that have 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 is 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 "/" can not be matched by a wildcard, only by "/".
--no-wildcards Wildcards are not permitted. Filenames 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 will use the compress program when operating on files.

Environment

The following environment variables affect the operation of tar:

SIMPLE_BACKUP_SUFFIX Filename 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 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 filename (*.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 is 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.

Related commands

ar — GNU utility for basic manipulation of archives
basename — Strip the directory components from pathnames
cd — Change the working directory
chown — Change the owner of a file or files
cpio — Copy files into or out of an archive
dirname — Strip the filename component from pathnames
ls — Output a list of files or directories, and their properties
mt — Control a magnetic tape device
zcat — Display the contents of a gzip archive