Python tarfile

Open an archive

Use tarfile.open to open an archive. The mode string selects the action and the compression.

The mode "r:gz" reads a gzip-compressed tar file. The mode "w:gz" writes a new gzip-compressed tar file. The mode "r" reads a plain tar file with no compression.

Always close the archive. A with block closes it for you, even when an error occurs.

import tarfile

with tarfile.open("data.tar.gz", "r:gz") as tar:
    print(tar.getnames())

with tarfile.open("new.tar.gz", "w:gz") as tar:
    pass

List the members

The getnames method returns a list of member names. Each name is the path stored inside the archive.

The getmembers method returns TarInfo objects. Each object has a name and a size in bytes.

Loop over the members to read the name and the size of each file. The code below prints one line for each member.

import tarfile

with tarfile.open("data.tar.gz", "r:gz") as tar:
    for member in tar.getmembers():
        print(member.name, member.size)

Extract files with a filter

The extractall method writes the members to a target folder. In Python 3.12 and later, pass filter="data" to extractall.

The data filter blocks path traversal. A member with a name such as ../secret.txt cannot write outside the target folder. The filter also blocks unsafe links and device files.

The code below extracts the archive into the folder out. The call raises an error if a member is not safe.

import tarfile

with tarfile.open("data.tar.gz", "r:gz") as tar:
    tar.extractall(path="out", filter="data")

Add files with arcname

The add method puts a file into the archive. By default, the archive keeps the full local path of the file.

Pass arcname to set the name inside the archive. Then the archive does not keep the local path.

The code below adds the file build/report.txt as report.txt. A reader of the archive sees only report.txt.

import tarfile

with tarfile.open("out.tar.gz", "w:gz") as tar:
    tar.add("build/report.txt", arcname="report.txt")

Write to a BytesIO stream

You can write an archive to memory instead of a file. Pass a BytesIO object as the fileobj argument.

Set the mode to "w:gz" and give the mode "w" to the BytesIO object. After you close the tar archive, call getvalue to read the bytes.

The code below builds an archive in memory and prints its size. No file touches the disk.

import io
import tarfile

buffer = io.BytesIO()
with tarfile.open(fileobj=buffer, mode="w:gz") as tar:
    tar.add("build/report.txt", arcname="report.txt")
print(len(buffer.getvalue()))

Treat untrusted archives with care

An archive from an untrusted source can contain unsafe member names. A name with .. can point outside the target folder. A link can point to a sensitive file.

Always pass filter="data" to extractall on Python 3.12 and later. On older versions, check each member name before you extract it.

A common mistake is to call extractall with no filter. The fix is to add filter="data". This one change blocks path traversal outside the target folder.

Common questions

How do I read a .tar.gz file?

Call tarfile.open with the mode "r:gz". Then use getnames or getmembers to list the contents, or extractall to write the files.

Is extractall safe?

It is safe only when you trust the archive or pass filter="data" on Python 3.12 and later. The filter blocks path traversal and unsafe links.

How do I add a file to an archive?

Open the archive in a write mode such as "w:gz" and call add with the file path. Pass arcname to set the name stored inside the archive.