Python

Python tarfile — Create, List, and Extract Tar Archives

A tar archive packs many files into one stream while keeping each file's name, size, mode, and modification time. The tarfile module creates, reads, and extracts those archives with no package to install, and it handles the gzip, bz2, and xz compressed forms through the same interface. This guide builds archives in memory so every result is exact, then lists and reads them back, walks their members one at a time, extracts them to a real folder with a safety filter, and covers the errors an archive from someone else can raise.

Written November 17, 2026 · Tested with Python 3.12.3 · 13 min read

By the end of this guide
  • Creating an archive: TarInfo and addfile
  • Listing members: getnames, getmember, and getmembers
  • Reading contents: extractfile
  • Compression modes and transparent reading

Written November 17, 2026

Tested with Python 3.12.3

What this guide is

The tarfile module reads and writes tar archives. An archive is a sequence of members, and each member is described by a TarInfo object that carries its name, size, mode, modification time, and type, followed by the file's data when the member is a regular file. Opening an archive with tarfile.open gives a TarFile object: addfile writes a member, getmembers and getnames list what is inside, extractfile reads a member's data without touching disk, and extractall writes members out to a folder. Every program in this guide works in memory with io.BytesIO, fixed modification times, and fixed sizes, so the output is the same on every run.

Creating an archive: TarInfo and addfile

To add data that is already in memory, build a TarInfo for the name, set its size to the length of the data, set mtime and mode, and pass it to addfile with a BytesIO object holding the data. A folder member is a TarInfo whose type is DIRTYPE and whose size is zero. A plain tar stream is padded to a fixed record size, so a small archive opened with mode "w" is 10240 bytes long:

Python
import io, tarfile

def add(tf, name, data, mtime=1700000000):
    info = tarfile.TarInfo(name)
    info.size = len(data)
    info.mtime = mtime
    info.mode = 0o644
    tf.addfile(info, io.BytesIO(data))

buf = io.BytesIO()
with tarfile.open(fileobj=buf, mode="w") as tf:
    add(tf, "hello.txt", b"Hello, tarfile!\n")
    add(tf, "notes/readme.txt", b"Read me first.\n")
    folder = tarfile.TarInfo("notes")
    folder.type = tarfile.DIRTYPE
    folder.mtime = 1700000000
    folder.mode = 0o755
    tf.addfile(folder)
print(len(buf.getvalue()))
buf.seek(0)
with tarfile.open(fileobj=buf, mode="r:") as tf:
    for member in tf.getmembers():
        print(member.name, member.size, member.isfile(), member.isdir(), member.mtime)

The exact output:

Output
10240
hello.txt 16 True False 1700000000
notes/readme.txt 15 True False 1700000000
notes 0 False True 1700000000

The size on the TarInfo must match the data that follows it, because the reader uses that size to find the next member. Setting mtime explicitly is what makes an archive reproducible: two runs that add the same names, sizes, modes, and times produce the same plain tar bytes. For files that already exist on disk, add takes a path and reads the TarInfo from the file itself, and gettarinfo builds that TarInfo without adding it.

Listing members: getnames, getmember, and getmembers

Three methods answer three different questions about an archive that is open for reading. getnames returns the member names as a list of strings, in archive order. getmembers returns the TarInfo objects for every member, in the same order. getmember returns the one TarInfo for a name, and raises KeyError when the archive holds no member with that name:

Python
import io, tarfile

def build():
    buf = io.BytesIO()
    with tarfile.open(fileobj=buf, mode="w") as tf:
        for name, data in (("a.txt", b"alpha\n"), ("b/c.txt", b"gamma\n")):
            info = tarfile.TarInfo(name)
            info.size = len(data)
            info.mtime = 1700000000
            info.mode = 0o644
            tf.addfile(info, io.BytesIO(data))
    buf.seek(0)
    return buf

with tarfile.open(fileobj=build(), mode="r:") as tf:
    print(tf.getnames())
    member = tf.getmember("b/c.txt")
    print(member.name, member.size, member.isfile())
    print([m.name for m in tf.getmembers()])
    try:
        tf.getmember("missing.txt")
    except KeyError as e:
        print(type(e).__name__ + ":", e)

The exact output:

Output
['a.txt', 'b/c.txt']
b/c.txt 6 True
['a.txt', 'b/c.txt']
KeyError: "filename 'missing.txt' not found"

Listing is the safe first step with an archive from any source: the names, sizes, and types are visible before a single byte is extracted. A name with a folder part, such as b/c.txt, is one member, not two, and the folder part does not by itself create a folder member in the list.

Reading contents: extractfile

extractfile returns a readable file object for a regular-file member, so a program can read the data in place without extracting anything. It also returns a readable object for a link member, and reading it gives the link target's data. It returns None for the other member types, such as a folder, it raises KeyError for a name that is not in the archive, and it accepts either a member name or a TarInfo object:

Python
import io, tarfile

def build():
    buf = io.BytesIO()
    with tarfile.open(fileobj=buf, mode="w") as tf:
        for name, data in (("hello.txt", b"Hello, tarfile!\n"), ("data.csv", b"id,name\n1,Ada\n2,Grace\n")):
            info = tarfile.TarInfo(name)
            info.size = len(data)
            info.mtime = 1700000000
            info.mode = 0o644
            tf.addfile(info, io.BytesIO(data))
        folder = tarfile.TarInfo("folder")
        folder.type = tarfile.DIRTYPE
        folder.mtime = 1700000000
        folder.mode = 0o755
        tf.addfile(folder)
    buf.seek(0)
    return buf

with tarfile.open(fileobj=build(), mode="r:") as tf:
    print(tf.extractfile("hello.txt").read())
    print(tf.extractfile("data.csv").read().decode(), end="")
    print(tf.extractfile("folder"))

The exact output:

Output
b'Hello, tarfile!\n'
id,name
1,Ada
2,Grace
None

The first line is bytes, because extractfile makes no guess about encoding, and the second line decodes the same kind of result to text explicitly. Reading in place is the right default for inspection, counting, and conversion work: nothing lands on disk, and a member that turns out to be a folder is easy to skip by checking for None. A link is not skipped that way, because extractfile follows it to the target's data; test isfile or issym on its TarInfo first when links need different handling.

Compression modes and transparent reading

The mode string chooses compression when an archive is written. Mode "w" writes a plain tar stream, "w:gz" writes gzip compression, "w:bz2" writes bzip2 compression, and "w:xz" writes lzma compression. For reading, mode "r:*" opens any of those forms transparently, detecting the compression from the stream itself, while "r:" reads only a plain tar stream and "r:gz", "r:bz2", and "r:xz" each read one named form:

Python
import io, tarfile

def write(mode):
    buf = io.BytesIO()
    with tarfile.open(fileobj=buf, mode=mode) as tf:
        data = b"repeat repeat repeat\n"
        info = tarfile.TarInfo("r.txt")
        info.size = len(data)
        info.mtime = 1700000000
        info.mode = 0o644
        tf.addfile(info, io.BytesIO(data))
    buf.seek(0)
    return buf

for mode in ("w", "w:gz", "w:bz2", "w:xz"):
    buf = write(mode)
    with tarfile.open(fileobj=buf, mode="r:*") as tf:
        print(mode, tf.extractfile("r.txt").read().decode().strip())
print(len(write("w").getvalue()))

The exact output:

Output
w repeat repeat repeat
w:gz repeat repeat repeat
w:bz2 repeat repeat repeat
w:xz repeat repeat repeat
10240

Every compressed form reads back to the same member data through the one transparent mode, which is why "r:*" is the usual choice for a reader that accepts archives from other people or other tools. Compression changes the size of the stream, not the members inside it: names, sizes, modes, and times survive the round trip unchanged. The plain length on the last line is exact because a plain tar stream is padded to whole records, as the first program showed.

Walking members one at a time: next and TarInfo

getmembers reads the whole index at once. The next method instead returns one TarInfo at a time, in archive order, and returns None when the archive is exhausted, which suits a large archive that a program wants to scan without holding the full list. The TarInfo query methods describe each member: isreg reports a regular file, isdir a folder, and issym a symbolic link whose target is in linkname:

Python
import io, tarfile

buf = io.BytesIO()
with tarfile.open(fileobj=buf, mode="w") as tf:
    data = b"12345"
    info = tarfile.TarInfo("x.txt")
    info.size = len(data)
    info.mtime = 1700000000
    info.mode = 0o644
    tf.addfile(info, io.BytesIO(data))
    folder = tarfile.TarInfo("docs")
    folder.type = tarfile.DIRTYPE
    folder.mtime = 1700000000
    folder.mode = 0o755
    tf.addfile(folder)
    link = tarfile.TarInfo("x-link")
    link.type = tarfile.SYMTYPE
    link.linkname = "x.txt"
    link.mtime = 1700000000
    link.mode = 0o777
    tf.addfile(link)
buf.seek(0)
with tarfile.open(fileobj=buf, mode="r:") as tf:
    member = tf.next()
    print(member.name, member.size, member.isreg(), oct(member.mode), member.mtime)
    member = tf.next()
    print(member.name, member.size, member.isdir(), oct(member.mode), member.mtime)
    member = tf.next()
    print(member.name, member.issym(), member.linkname, oct(member.mode), member.mtime)
    print(tf.next())

The exact output:

Output
x.txt 5 True 0o644 1700000000
docs 0 True 0o755 1700000000
x-link True x.txt 0o777 1700000000
None

A TarFile object is also iterable, and iterating it yields the same members in the same order. The type tests matter before any extraction decision: a regular file has data to read, a folder has none, and a link points at another name, which is a name a careful reader checks before following it.

Extracting to a folder: extractall with the data filter

extractall writes every member under a destination folder, creating folder members as folders and writing regular files with their data. Passing filter="data" applies the data filter, which strips dangerous parts of a member before it is written: absolute names lose their leading separator, names that would land outside the destination are refused, and link targets that point outside are refused. This program extracts to a real temporary folder and prints only member names and contents, never a folder path:

Python
import io, pathlib, tarfile, tempfile

buf = io.BytesIO()
with tarfile.open(fileobj=buf, mode="w") as tf:
    for name, data in (("one.txt", b"one\n"), ("sub/two.txt", b"two\n")):
        info = tarfile.TarInfo(name)
        info.size = len(data)
        info.mtime = 1700000000
        info.mode = 0o644
        tf.addfile(info, io.BytesIO(data))
buf.seek(0)
with tempfile.TemporaryDirectory() as td:
    with tarfile.open(fileobj=buf, mode="r:") as tf:
        tf.extractall(td, filter="data")
    root = pathlib.Path(td)
    for path in sorted(root.rglob("*"), key=lambda p: p.relative_to(root).as_posix()):
        rel = path.relative_to(root).as_posix()
        print(rel, path.is_file(), path.read_text().strip() if path.is_file() else "-")

The exact output:

Output
one.txt True one
sub False -
sub/two.txt True two

The member sub/two.txt produced both the sub folder and the file inside it, even though the archive held no separate folder member for sub. For one member at a time, extract takes a member name or TarInfo, a destination, and the same filter argument. Naming the filter on every extraction call is the habit to keep: it states, in the code itself, which safety rules the extraction runs under.

The documentation for this module warns against extracting archives from untrusted sources without prior inspection, because a member name can use ../ parts to point outside the destination folder, and a link member can point at a file elsewhere on the system. The data filter blocks both shapes: a name that would be extracted outside the destination raises OutsideDestinationError, and a symbolic link with an absolute target raises AbsoluteLinkError. Data that is not a tar stream at all raises ReadError when it is opened for reading. This program prints only the error type names, because the full messages for the first two errors contain the destination path:

Python
import io, tarfile, tempfile

def build_member(info, data=None):
    buf = io.BytesIO()
    with tarfile.open(fileobj=buf, mode="w") as tf:
        if data is None:
            tf.addfile(info)
        else:
            info.size = len(data)
            tf.addfile(info, io.BytesIO(data))
    buf.seek(0)
    return buf

evil = tarfile.TarInfo("../evil.txt")
evil.mtime = 1700000000
evil.mode = 0o644
with tempfile.TemporaryDirectory() as td:
    with tarfile.open(fileobj=build_member(evil, b"evil\n"), mode="r:") as tf:
        try:
            tf.extractall(td, filter="data")
        except tarfile.FilterError as e:
            print(type(e).__name__)
link = tarfile.TarInfo("bad-link")
link.type = tarfile.SYMTYPE
link.linkname = "/etc/passwd"
link.mtime = 1700000000
with tempfile.TemporaryDirectory() as td:
    with tarfile.open(fileobj=build_member(link), mode="r:") as tf:
        try:
            tf.extractall(td, filter="data")
        except tarfile.FilterError as e:
            print(type(e).__name__)
try:
    with tarfile.open(fileobj=io.BytesIO(b"not a tar"), mode="r:"):
        pass
except tarfile.ReadError as e:
    print(type(e).__name__ + ":", e)

The exact output:

Output
OutsideDestinationError
AbsoluteLinkError
ReadError: truncated header

Both filter errors are subclasses of FilterError, so one except tarfile.FilterError clause catches the whole family. The plain reading rule follows from these three lines: list an unfamiliar archive first, read members with extractfile when disk copies are not needed, and extract with filter="data" when they are. An archive a program built itself, from its own names and data, carries none of these risks, and the filter still costs nothing to name.

Which choice for which job

Job Choice Why
Add data already in memory TarInfo plus addfile The name, size, mode, and time are set explicitly, with a BytesIO object as the data
Add a file that exists on disk add Reads the file and its own information from the path
See what an archive holds getnames or getmembers Names alone, or the full TarInfo for every member, before anything is extracted
Read one member in place extractfile Returns a readable object for a regular file or a link, and None for other types such as folders
Read an archive of unknown compression Mode "r:*" Detects gzip, bzip2, lzma, or plain form from the stream
Write a compressed archive Mode "w:gz", "w:bz2", or "w:xz" One mode string picks the compression; the member interface is unchanged
Extract an archive from someone else extractall with filter="data" Refuses names and links that point outside the destination

Checklist

  • Set size on every TarInfo to the exact length of the data passed to addfile.
  • Set mtime and mode explicitly when an archive needs to be reproducible.
  • List an unfamiliar archive with getnames or getmembers before extracting it.
  • Use extractfile to read a member in place, and check for None before reading a member that may be a folder or another type that is neither a regular file nor a link.
  • Open archives of unknown compression with "r:*", and pick a compressed write mode only when the smaller stream is worth it.
  • Extract with filter="data" every time, and catch FilterError around extraction of an archive from another source.
  • Catch ReadError around opening data that may not be a tar stream at all.

Sources

  • Python Standard Library, tarfile — tarfile.open and its modes, TarFile and TarInfo, addfile, getmembers, getnames, getmember, extractfile, extractall and the extraction filters including data_filter, the warning about extracting untrusted archives, and the ReadError and FilterError exceptions.

Keep Exploring