7.19 tarfile -- Read and write tar archive files

Python PEP

7.19 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:

  • reads and writes gzip and bzip2 compressed archives.
  • creates POSIX 1003.1-1990 compliant or GNU tar compatible archives.
  • reads GNU tar extensions longname, longlink and sparse.
  • stores pathnames of unlimited length using GNU tar extensions.
  • handles directories, regular files, hardlinks, symbolic links, fifos, character devices and block devices and is able to acquire and restore file information like timestamp, access permissions and owner.
  • can handle tape devices.

Return a TarFile object for the pathname name. For detailed information on TarFile objects, see TarFile Objects (section 7.19.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' 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.

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 7.19.3). The currently possible modes:

Mode Action
'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 for reading and writing tar archives. Do not use this class directly, better use open() instead. See ``TarFile Objects'' (section 7.19.1).

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

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.

Base class for all tarfile exceptions.

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

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

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

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

See Also:

Documentation of the zipfile standard module.

Documentation for tar archive files, including GNU tar extensions.


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