pydoc > tarfile

man perldoc info pydoc3 ri search

📖 NAME

tarfile — Read from and write to tar format archives.

🚀 Quick Reference

Use Case	Command	Description
📂 Open tar archive for reading (auto-detect compression)	tarfile.open('archive.tar.gz', 'r')	Opens with transparent compression; returns a TarFile object.
📦 Open tar for writing with gzip compression	tarfile.open('archive.tar.gz', 'w:gz')	Creates a new gzip-compressed tar archive.
➕ Add a file to an archive	tar.add('file.txt')	Adds file.txt to the open TarFile.
📤 Extract all members to current directory	tar.extractall()	Extracts all files, preserving metadata.
📋 List contents (table of files)	tar.list()	Prints an ls -l-style listing of archive members.
🔍 Check if a file is a tar archive	tarfile.is_tarfile('file')	Returns True if the file is a supported tar archive.
📄 Get a single member as a file object	tar.extractfile('member')	Returns an io.BufferedReader for regular files.

🔗 MODULE REFERENCE

https://docs.python.org/3.10/library/tarfile.html

The following documentation is automatically generated from the Python source files. It may be incomplete, incorrect or include features that are considered implementation detail and may vary between Python implementations. When in doubt, consult the module reference at the location listed above.

📚 CLASSES

• builtins.Exception(builtins.BaseException)
  • TarError
    • CompressionError
    • ExtractError
    • HeaderError
    • ReadError
    • StreamError
• builtins.object
  • TarFile
  • TarInfo

🐛 Exception Classes (all inherit from TarError)

All exception classes share the same method resolution order (TarError → builtins.Exception → builtins.BaseException → builtins.object) and inherit the following methods and data descriptors (listed once for TarError):

• __init__(self, /, *args, **kwargs) — Initialize self.
• __new__(*args, **kwargs) from builtins.type — Create and return a new object.
• __delattr__(self, name, /) — Implement delattr(self, name).
• __getattribute__(self, name, /) — Return getattr(self, name).
• __reduce__(...) — Helper for pickle.
• __repr__(self, /) — Return repr(self).
• __setattr__(self, name, value, /) — Implement setattr(self, name, value).
• __setstate__(...)
• __str__(self, /) — Return str(self).
• with_traceback(...) — Set __traceback__ and return self.
• Data descriptors: __weakref__, __cause__, __context__, __dict__, __suppress_context__, __traceback__, args

CompressionError

Exception for unavailable compression methods.

ExtractError

General exception for extract errors.

HeaderError

Base exception for header errors.

ReadError

Exception for unreadable tar archives.

StreamError

Exception for unsupported operations on stream-like TarFiles.

📦 TarFile class

TarFile(name=None, mode='r', fileobj=None, format=None, tarinfo=None, dereference=None, ignore_zeros=None, encoding=None, errors='surrogateescape', pax_headers=None, debug=None, errorlevel=None, copybufsize=None)

The TarFile Class provides an interface to tar archives.

Methods

• __enter__(self)
• __exit__(self, type, value, traceback)
• __init__(self, name=None, mode='r', fileobj=None, format=None, tarinfo=None, dereference=None, ignore_zeros=None, encoding=None, errors='surrogateescape', pax_headers=None, debug=None, errorlevel=None, copybufsize=None) — Open an (uncompressed) tar archive name. mode is either 'r' to read, 'a' to append, or 'w' to create a new file. Defaults to 'r'.
• __iter__(self) — Provide an iterator object.
• add(self, name, arcname=None, recursive=True, *, filter=None) — Add the file name to the archive. arcname specifies an alternative name. Directories are added recursively by default. filter is a function that expects a TarInfo argument and returns the changed TarInfo (or None to exclude).
• addfile(self, tarinfo, fileobj=None) — Add the TarInfo object tarinfo to the archive. If fileobj is given, it should be a binary file, and tarinfo.size bytes are read from it.
• chmod(self, tarinfo, targetpath) — Set file permissions of targetpath according to tarinfo.
• chown(self, tarinfo, targetpath, numeric_owner) — Set owner of targetpath according to tarinfo. If numeric_owner is True, use .gid/.uid instead of .gname/.uname.
• close(self) — Close the TarFile. In write-mode, two finishing zero blocks are appended.
• extract(self, member, path='', set_attrs=True, *, numeric_owner=False, filter=None) — Extract a member from the archive to the current working directory, using its full name. member may be a filename or TarInfo object. filter can be a function or string name of a common filter.
• extractall(self, path='.', members=None, *, numeric_owner=False, filter=None) — Extract all members from the archive to the current working directory. members is optional and must be a subset of getmembers().
• extractfile(self, member) — Extract a member as a file object. Returns an io.BufferedReader for regular files or links, None otherwise. Raises KeyError if not found.
• getmember(self, name) — Return a TarInfo object for member name. Raises KeyError if not found.
• getmembers(self) — Return the members of the archive as a list of TarInfo objects.
• getnames(self) — Return the members as a list of their names.
• gettarinfo(self, name=None, arcname=None, fileobj=None) — Create a TarInfo object from the result of os.stat on an existing file.
• list(self, verbose=True, *, members=None) — Print a table of contents to sys.stdout. If verbose is False, only names are printed.
• makedev(self, tarinfo, targetpath) — Make a character or block device called targetpath.
• makedir(self, tarinfo, targetpath) — Make a directory called targetpath.
• makefifo(self, tarinfo, targetpath) — Make a fifo called targetpath.
• makefile(self, tarinfo, targetpath) — Make a file called targetpath.
• makelink(self, tarinfo, targetpath) — Make a (symbolic) link called targetpath.
• makeunknown(self, tarinfo, targetpath) — Make a file from a TarInfo object with an unknown type at targetpath.
• next(self) — Return the next member of the archive as a TarInfo object, or None if no more.
• utime(self, tarinfo, targetpath) — Set modification time of targetpath according to tarinfo.

Class Methods

• bz2open(name, mode='r', fileobj=None, compresslevel=9, **kwargs) from builtins.type — Open bzip2 compressed tar archive for reading or writing. Appending is not allowed.
• gzopen(name, mode='r', fileobj=None, compresslevel=9, **kwargs) from builtins.type — Open gzip compressed tar archive for reading or writing. Appending is not allowed.
• open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs) from builtins.type — Open a tar archive for reading, writing or appending. Returns an appropriate TarFile class. See mode descriptions below.
• taropen(name, mode='r', fileobj=None, **kwargs) from builtins.type — Open uncompressed tar archive for reading or writing.
• xzopen(name, mode='r', fileobj=None, preset=None, **kwargs) from builtins.type — Open lzma compressed tar archive for reading or writing. Appending is not allowed.

Data Descriptors

• __dict__ — dictionary for instance variables
• __weakref__ — list of weak references

Data and Other Attributes

• OPEN_METH = {'bz2': 'bz2open', 'gz': 'gzopen', 'tar': 'taropen', 'xz': 'xzopen'}
• debug = 0
• dereference = False
• encoding = 'utf-8'
• errorlevel = 1
• errors = None
• extraction_filter = None
• fileobject = <class 'tarfile.ExFileObject'>
• format = 2
• ignore_zeros = False
• tarinfo = <class 'tarfile.TarInfo'>

ℹ️ TarInfo class

TarInfo(name='')

Informational class which holds the details about an archive member given by a tar header block. Objects are returned by TarFile.getmember(), TarFile.getmembers() and TarFile.gettarinfo().

Methods

• __init__(self, name='') — Construct a TarInfo object. name is the optional name of the member.
• __repr__(self) — Return repr(self).
• create_gnu_header(self, info, encoding, errors) — Return the object as a GNU header block sequence.
• create_pax_header(self, info, encoding) — Return the object as a ustar header block. If it cannot be represented this way, prepend a pax extended header sequence with supplement information.
• create_ustar_header(self, info, encoding, errors) — Return the object as a ustar header block.
• get_info(self) — Return the TarInfo's attributes as a dictionary.
• isblk(self) — Return True if it is a block device.
• ischr(self) — Return True if it is a character device.
• isdev(self) — Return True if it is one of character device, block device or FIFO.
• isdir(self) — Return True if it is a directory.
• isfifo(self) — Return True if it is a FIFO.
• isfile(self) — Return True if the TarInfo object is a regular file.
• islnk(self) — Return True if it is a hard link.
• isreg(self) — Return True if the TarInfo object is a regular file.
• issparse(self)
• issym(self) — Return True if it is a symbolic link.
• replace(self, *, name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True, _KEEP=...) — Return a deep copy of self with the given attributes replaced.
• tobuf(self, format=2, encoding='utf-8', errors='surrogateescape') — Return a tar header as a string of 512 byte blocks.

Class Methods

• create_pax_global_header(pax_headers) from builtins.type — Return the object as a pax global header block sequence.
• frombuf(buf, encoding, errors) from builtins.type — Construct a TarInfo object from a 512 byte bytes object. Supports old v7 tar format headers.
• fromtarfile(tarfile) from builtins.type — Return the next TarInfo object from TarFile object tarfile.

Data Descriptors

• chksum — Header checksum.
• devmajor — Device major number.
• devminor — Device minor number.
• gid — Group ID of the user who originally stored this member.
• gname — Group name.
• linkname — Name of the target file name (only present for LNKTYPE and SYMTYPE).
• linkpath — In pax headers, "linkname" is called "linkpath".
• mode — Permission bits.
• mtime — Time of last modification.
• name — Name of the archive member.
• offset — The tar header starts here.
• offset_data — The file's data starts here.
• path — In pax headers, "name" is called "path".
• pax_headers — A dictionary of key-value pairs from an associated pax extended header.
• size — Size in bytes.
• sparse — Sparse member information.
• tarfile
• type — File type (one of REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE).
• uid — User ID of the user who originally stored this member.
• uname — User name.

🛠️ FUNCTIONS

is_tarfile(name)

Return True if name points to a tar archive that we are able to handle, else return False. name should be a string, file, or file-like object.

open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

Open a tar archive for reading, writing or appending. Return an appropriate TarFile class.

Mode descriptions:

• 'r' or 'r:*' — open for reading with transparent compression
• 'r:' — open for reading exclusively uncompressed
• 'r:gz' — open for reading with gzip compression
• 'r:bz2' — open for reading with bzip2 compression
• 'r:xz' — open for reading with lzma compression
• 'a' or 'a:' — open for appending, creating the file if necessary
• 'w' or 'w:' — open for writing without compression
• 'w:gz' — open for writing with gzip compression
• 'w:bz2' — open for writing with bzip2 compression
• 'w:xz' — open for writing with lzma compression
• 'x' or 'x:' — create a tarfile exclusively without compression, raise an exception if the file already exists
• 'x:gz' — create a gzip compressed tarfile exclusively
• 'x:bz2' — create a bzip2 compressed tarfile exclusively
• 'x:xz' — create an lzma compressed tarfile exclusively
• 'r|*' — open a stream of tar blocks with transparent compression
• 'r|' — open an uncompressed stream of tar blocks for reading
• 'r|gz' — open a gzip compressed stream of tar blocks
• 'r|bz2' — open a bzip2 compressed stream of tar blocks
• 'r|xz' — open an lzma compressed stream of tar blocks
• 'w|' — open an uncompressed stream for writing
• 'w|gz' — open a gzip compressed stream for writing
• 'w|bz2' — open a bzip2 compressed stream for writing
• 'w|xz' — open an lzma compressed stream for writing

📊 DATA

• DEFAULT_FORMAT = 2
• ENCODING = 'utf-8'
• GNU_FORMAT = 1
• PAX_FORMAT = 2
• USTAR_FORMAT = 0
• __all__ = ['TarFile', 'TarInfo', 'is_tarfile', 'TarError', 'ReadError', ...]

👤 AUTHOR

Lars Gustäbel (lars AT gustaebel.de)

📝 CREDITS

Gustavo Niemeyer, Niels Gustäbel, Richard Townsend.

📁 FILE

/usr/lib/python3.10/tarfile.py

📖 NAME 🚀 Quick Reference 🔗 MODULE REFERENCE 📚 CLASSES 🛠️ FUNCTIONS 📊 DATA 👤 AUTHOR 📝 CREDITS 📁 FILE