12.5 tarfile -- Read and write tar archive files

New in version 2.3.

The tarfile module makes it possible to read and create tar archives. Some facts and figures:

open( [name[, mode [, fileobj[, bufsize]]]])
Return a TarFile object for the pathname name. For detailed information on TarFile objects, see TarFile Objects (section 12.5.1).

mode has to be a string of the form 'filemode[:compression]', it defaults to 'r'. Here is a full list of mode combinations:

mode action
'r' or 'r:*' Open for reading with transparent compression (recommended).
'r:' Open for reading exclusively without compression.
'r:gz' Open for reading with gzip compression.
'r:bz2' Open for reading with bzip2 compression.
'a' or 'a:' Open for appending with no compression.
'w' or 'w:' Open for uncompressed writing.
'w:gz' Open for gzip compressed writing.
'w:bz2' Open for bzip2 compressed writing.

Note that 'a:gz' or 'a:bz2' is not possible. If mode is not suitable to open a certain (compressed) file for reading, ReadError is raised. Use mode 'r' to avoid this. If a compression method is not supported, CompressionError is raised.

If fileobj is specified, it is used as an alternative to a file object opened for name. It is supposed to be at position 0.

For special purposes, there is a second format for mode: 'filemode|[compression]'. open() will return a TarFile object that processes its data as a stream of blocks. No random seeking will be done on the file. If given, fileobj may be any object that has a read() or write() method (depending on the mode). bufsize specifies the blocksize and defaults to 20 * 512 bytes. Use this variant in combination with e.g. sys.stdin, a socket file object or a tape device. However, such a TarFile object is limited in that it does not allow to be accessed randomly, see ``Examples'' (section 12.5.3). The currently possible modes:

Mode Action
'r|*' Open a stream of tar blocks for reading with transparent compression.
'r|' Open a stream of uncompressed tar blocks for reading.
'r|gz' Open a gzip compressed stream for reading.
'r|bz2' Open a bzip2 compressed stream for reading.
'w|' Open an uncompressed stream for writing.
'w|gz' Open an gzip compressed stream for writing.
'w|bz2' Open an bzip2 compressed stream for writing.

class TarFile
Class for reading and writing tar archives. Do not use this class directly, better use open() instead. See ``TarFile Objects'' (section 12.5.1).

is_tarfile( name)
Return True if name is a tar archive file, that the tarfile module can read.

class TarFileCompat( filename[, mode[, compression]])
Class for limited access to tar archives with a zipfile-like interface. Please consult the documentation of the zipfile module for more details. compression must be one of the following constants:
Constant for an uncompressed tar archive.
Constant for a gzip compressed tar archive.

exception TarError
Base class for all tarfile exceptions.

exception ReadError
Is raised when a tar archive is opened, that either cannot be handled by the tarfile module or is somehow invalid.

exception CompressionError
Is raised when a compression method is not supported or when the data cannot be decoded properly.

exception StreamError
Is raised for the limitations that are typical for stream-like TarFile objects.

exception ExtractError
Is raised for non-fatal errors when using extract(), but only if TarFile.errorlevel == 2.

See Also:

Module zipfile:
Documentation of the zipfile standard module.

GNU tar manual, Basic Tar Format
Documentation for tar archive files, including GNU tar extensions.

See About this document... for information on suggesting changes.