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
- 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:
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:
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:
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:
['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:
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:
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:
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:
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:
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:
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:
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:
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.
Untrusted archives: traversal, links, and read errors
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:
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:
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
sizeon everyTarInfoto the exact length of the data passed toaddfile. - Set
mtimeandmodeexplicitly when an archive needs to be reproducible. - List an unfamiliar archive with
getnamesorgetmembersbefore extracting it. - Use
extractfileto 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 catchFilterErroraround extraction of an archive from another source. - Catch
ReadErroraround opening data that may not be a tar stream at all.
Related guides on this site
- Python
zipfile— Create, List, Read, and Extract — the same create, list, read, and extract work for zip archives instead of tar archives. - Python shutil — Copy, Move, Archive, and Clean Up — the high-level archive helpers that pack and unpack whole folders in one call, built on modules including this one.
- Python pathlib — Paths, Parts, and Files — the path objects used to inspect what an extraction wrote to a folder.
Sources
- Python Standard Library,
tarfile—tarfile.openand its modes,TarFileandTarInfo,addfile,getmembers,getnames,getmember,extractfile,extractalland the extraction filters includingdata_filter, the warning about extracting untrusted archives, and theReadErrorandFilterErrorexceptions.
Keep Exploring
The full Python hub \u2014 language basics, the standard library, and data tools.
Every guide on the site in one list, grouped by topic.
Every browser-only checker and verifier on the site.
The C++, Python, Sysadmin, Rust, Go, and TypeScript hubs.