tarfile

Key Features

• Supports reading and writing of tar archives
• Handles both compressed (gzip, bzip2, lzma, zstd) and uncompressed tar files
• Provides random access to archive members
• Allows for adding and extracting files from tar archives
• Works with both files on disk and file-like objects—including in-memory archives
• Enables inspection and modification of file metadata
• Applies the "data" extraction filter by default since Python 3.14 to block unsafe members such as absolute paths, links that escape the destination, and device files

Frequently Used Classes and Functions

Examples

Open and list the contents of a tar archive:

>>> import tarfile
>>> with tarfile.open("example.tar.gz", mode="r:gz") as tar_file:
...     tar_file.list()
...

Extract a specific file from a tar archive:

>>> with tarfile.open("example.tar.gz", mode="r:gz") as tar_file:
...     tar_file.extract("file1.txt", path="./extracted", filter="data")
...

Create a new tar archive and add files to it:

>>> with tarfile.open("new_archive.tar", mode="w") as tar_file:
...     tar_file.add("file1.txt")
...     tar_file.add("file2.txt")
...

Common Use Cases

• Archiving and compressing multiple files or directories into a single tar archive
• Extracting specific files or all contents from tar archives
• Inspecting archive contents, including file metadata, without extraction
• Selectively extracting or adding files based on patterns or criteria
• Creating automated backups of directories or projects
• Working with archives entirely in memory
• Preserving or modifying file permissions, timestamps, and ownership, by opting in to filter="tar" or filter="fully_trusted" on extraction
• Automating deployment, packaging, or continuous integration tasks

Real-World Example

Suppose you want to back up a directory of text files into a compressed tar archive using a function to perform the backup. You can use the tarfile module to accomplish this task efficiently:

>>> import tarfile, pathlib

>>> def backup_txt_files(source_dir, archive_name):
...     source_dir = pathlib.Path(source_dir)
...     archive_name = pathlib.Path(archive_name)
...     files_to_backup = list(source_dir.glob("*.txt"))
...     if not files_to_backup:
...         print("No files to back up")
...         return
...     with tarfile.open(archive_name, mode="w:gz") as tar_file:
...         for file_path in files_to_backup:
...             tar_file.add(file_path, arcname=file_path.name)
...     print("Files backed up successfully!")
...     return archive_name
...

>>> backup_txt_files("documents", "backup.tar.gz")
Files backed up successfully!

In this example, you create a function that collects all .txt files from the specified directory, creates a gzip-compressed tar archive containing those files, and returns a Path object representing the archive.

Related Resources

Tutorial

Python's zipfile: Manipulate Your ZIP Files Efficiently

In this guided tutorial, you'll learn how to manipulate ZIP files using Python's zipfile module from the standard library. Through hands-on examples, you'll learn how to read, write, compress, and extract files from your ZIP files quickly.

intermediate python stdlib

For additional information on related topics, take a look at the following resources:

• How to Get a List of All Files in a Directory With Python (Tutorial)
• Manipulating ZIP Files With Python (Course)
• Listing All Files in a Directory With Python (Course)