How to Use the Python tarfile Module

Python's built-in tarfile module provides a comprehensive suite of tools for reading, writing, and manipulating TAR archives, including those compressed with gzip, bz2, and lzma/xz formats. This article covers what the tarfile module accomplishes, its primary capabilities—such as inspecting archive contents, extracting files safely, and creating new archives—and practical examples of how to implement these features in your Python workflows without relying on external system utilities.

Core Capabilities of the tarfile Module

The tarfile module eliminates the need to shell out to system-level tar commands. It interacts directly with standard POSIX tar archives, handling low-level byte manipulation, header parsing, and directory structures natively.

1. Reading and Inspecting Archives

The module allows you to inspect the contents of an archive without extracting it to disk first. Using tarfile.open(), you can open an archive and inspect metadata such as file names, permissions, modification times, and file sizes.

• getnames(): Returns a list of file and directory paths inside the archive.
• getmembers(): Returns a list of TarInfo objects containing metadata for each item.
• extractfile(): Reads the contents of a specific file inside the archive as an in-memory binary stream.

import tarfile

with tarfile.open("backup.tar.gz", "r:gz") as tar:
    # Print all file names in the archive
    for name in tar.getnames():
        print(name)

2. Creating New Archives

The tarfile module allows you to create uncompressed or compressed archives and add files or entire directories into them using the add() method.

import tarfile

# Create a gzip-compressed archive
with tarfile.open("archive.tar.gz", "w:gz") as tar:
    # Add a single file
    tar.add("document.pdf")
    # Add an entire directory recursively
    tar.add("my_folder", arcname="stored_folder")

The arcname parameter allows you to rename the file or directory inside the archive so that local system paths are not exposed.

3. Extracting Archive Contents

Files can be extracted either individually or all at once. The module handles directory creation and file permissions automatically during extraction.

• extractall(): Extracts the entire archive to a specified destination directory.
• extract(): Extracts a single member identified by name or a TarInfo object.

import tarfile

with tarfile.open("archive.tar.gz", "r:gz") as tar:
    # Extract everything to a specific folder
    tar.extractall(path="./extracted_files")

Note: In modern Python versions (3.12+), you can use the filter parameter (such as filter='data') with extractall() to prevent directory traversal vulnerabilities like "Zip Slip."

4. Built-in Compression Support

The module handles compression transparently by changing the open mode flag passed to tarfile.open():

• "r" or "w": Uncompressed TAR.
• "r:gz" or "w:gz": Gzip compression (.tar.gz or .tgz).
• "r:bz2" or "w:bz2": Bzip2 compression (.tar.bz2).
• "r:xz" or "w:xz": LZMA/XZ compression (.tar.xz).
• "r:*": Automatically detects the compression format when reading.

Summary

The tarfile module serves as a complete, self-contained solution for archive management in Python. It enables scripts to package datasets, read compressed logs in-memory, generate downloadable backups, and unpack incoming files across Windows, macOS, and Linux without external dependencies.