/
usr
/
share
/
doc
/
python3-docs
/
html
/
library
/
/usr/share/doc/python3-docs/html/library
mkdir
upload
Name
Size
Mode
Actions
2to3.html
61709
0644
edit
dl
rm
abc.html
41394
0644
edit
dl
rm
aifc.html
28114
0644
edit
dl
rm
allos.html
32236
0644
edit
dl
rm
archiving.html
11992
0644
edit
dl
rm
argparse.html
274984
0644
edit
dl
rm
array.html
33547
0644
edit
dl
rm
ast.html
39595
0644
edit
dl
rm
asynchat.html
32546
0644
edit
dl
rm
asyncio-dev.html
51869
0644
edit
dl
rm
asyncio-eventloop.html
111215
0644
edit
dl
rm
asyncio-eventloops.html
33026
0644
edit
dl
rm
asyncio-protocol.html
87431
0644
edit
dl
rm
asyncio-queue.html
23957
0644
edit
dl
rm
asyncio-stream.html
61005
0644
edit
dl
rm
asyncio-subprocess.html
58015
0644
edit
dl
rm
asyncio-sync.html
35678
0644
edit
dl
rm
asyncio-task.html
83968
0644
edit
dl
rm
asyncio.html
28026
0644
edit
dl
rm
asyncore.html
42706
0644
edit
dl
rm
atexit.html
18433
0644
edit
dl
rm
audioop.html
35442
0644
edit
dl
rm
base64.html
36454
0644
edit
dl
rm
bdb.html
43423
0644
edit
dl
rm
binary.html
12723
0644
edit
dl
rm
binascii.html
24745
0644
edit
dl
rm
binhex.html
11669
0644
edit
dl
rm
bisect.html
25602
0644
edit
dl
rm
builtins.html
11604
0644
edit
dl
rm
bz2.html
33358
0644
edit
dl
rm
calendar.html
39539
0644
edit
dl
rm
cgi.html
55881
0644
edit
dl
rm
cgitb.html
12765
0644
edit
dl
rm
chunk.html
16872
0644
edit
dl
rm
cmath.html
34171
0644
edit
dl
rm
cmd.html
43811
0644
edit
dl
rm
code.html
27886
0644
edit
dl
rm
codecs.html
134071
0644
edit
dl
rm
codeop.html
14304
0644
edit
dl
rm
collections.abc.html
60912
0644
edit
dl
rm
collections.html
154946
0644
edit
dl
rm
colorsys.html
12627
0644
edit
dl
rm
compileall.html
28263
0644
edit
dl
rm
concurrency.html
21203
0644
edit
dl
rm
concurrent.futures.html
60660
0644
edit
dl
rm
concurrent.html
7959
0644
edit
dl
rm
configparser.html
141052
0644
edit
dl
rm
constants.html
17500
0644
edit
dl
rm
contextlib.html
88801
0644
edit
dl
rm
copy.html
13841
0644
edit
dl
rm
copyreg.html
14725
0644
edit
dl
rm
crypt.html
20331
0644
edit
dl
rm
crypto.html
10914
0644
edit
dl
rm
csv.html
69043
0644
edit
dl
rm
ctypes.html
264529
0644
edit
dl
rm
curses.ascii.html
25197
0644
edit
dl
rm
curses.html
175551
0644
edit
dl
rm
curses.panel.html
16706
0644
edit
dl
rm
custominterp.html
8734
0644
edit
dl
rm
datatypes.html
23950
0644
edit
dl
rm
datetime.html
306435
0644
edit
dl
rm
dbm.html
43119
0644
edit
dl
rm
debug.html
13983
0644
edit
dl
rm
decimal.html
233486
0644
edit
dl
rm
development.html
25123
0644
edit
dl
rm
difflib.html
96156
0644
edit
dl
rm
dis.html
106191
0644
edit
dl
rm
distribution.html
10506
0644
edit
dl
rm
distutils.html
10884
0644
edit
dl
rm
doctest.html
179752
0644
edit
dl
rm
dummy_threading.html
9316
0644
edit
dl
rm
email.charset.html
26431
0644
edit
dl
rm
email.compat32-message.html
86150
0644
edit
dl
rm
email.contentmanager.html
30028
0644
edit
dl
rm
email.encoders.html
14250
0644
edit
dl
rm
email.errors.html
19704
0644
edit
dl
rm
email.examples.html
57872
0644
edit
dl
rm
email.generator.html
41798
0644
edit
dl
rm
email.header.html
31219
0644
edit
dl
rm
email.headerregistry.html
57670
0644
edit
dl
rm
email.html
27741
0644
edit
dl
rm
email.iterators.html
13532
0644
edit
dl
rm
email.message.html
87210
0644
edit
dl
rm
email.mime.html
36081
0644
edit
dl
rm
email.parser.html
47430
0644
edit
dl
rm
email.policy.html
75241
0644
edit
dl
rm
email.util.html
33853
0644
edit
dl
rm
ensurepip.html
18700
0644
edit
dl
rm
enum.html
133949
0644
edit
dl
rm
errno.html
41331
0644
edit
dl
rm
exceptions.html
85151
0644
edit
dl
rm
faulthandler.html
23396
0644
edit
dl
rm
fcntl.html
27321
0644
edit
dl
rm
filecmp.html
25036
0644
edit
dl
rm
fileformats.html
11129
0644
edit
dl
rm
fileinput.html
30030
0644
edit
dl
rm
filesys.html
13418
0644
edit
dl
rm
fnmatch.html
16987
0644
edit
dl
rm
formatter.html
37666
0644
edit
dl
rm
fpectl.html
17538
0644
edit
dl
rm
fractions.html
29918
0644
edit
dl
rm
frameworks.html
13471
0644
edit
dl
rm
ftplib.html
54429
0644
edit
dl
rm
functional.html
9002
0644
edit
dl
rm
functions.html
201486
0644
edit
dl
rm
functools.html
64951
0644
edit
dl
rm
gc.html
29524
0644
edit
dl
rm
getopt.html
25353
0644
edit
dl
rm
getpass.html
12061
0644
edit
dl
rm
gettext.html
76641
0644
edit
dl
rm
glob.html
18432
0644
edit
dl
rm
grp.html
12383
0644
edit
dl
rm
gzip.html
32669
0644
edit
dl
rm
hashlib.html
79554
0644
edit
dl
rm
heapq.html
35529
0644
edit
dl
rm
hmac.html
17827
0644
edit
dl
rm
html.entities.html
11361
0644
edit
dl
rm
html.html
11108
0644
edit
dl
rm
html.parser.html
41842
0644
edit
dl
rm
http.client.html
65250
0644
edit
dl
rm
http.cookiejar.html
96195
0644
edit
dl
rm
http.cookies.html
39329
0644
edit
dl
rm
http.html
37602
0644
edit
dl
rm
http.server.html
58191
0644
edit
dl
rm
i18n.html
10464
0644
edit
dl
rm
idle.html
48412
0644
edit
dl
rm
imaplib.html
67339
0644
edit
dl
rm
imghdr.html
13456
0644
edit
dl
rm
imp.html
48153
0644
edit
dl
rm
importlib.html
173109
0644
edit
dl
rm
index.html
67768
0644
edit
dl
rm
inspect.html
130355
0644
edit
dl
rm
internet.html
31087
0644
edit
dl
rm
intro.html
9904
0644
edit
dl
rm
io.html
122685
0644
edit
dl
rm
ipaddress.html
105873
0644
edit
dl
rm
ipc.html
33743
0644
edit
dl
rm
itertools.html
132824
0644
edit
dl
rm
json.html
81078
0644
edit
dl
rm
keyword.html
8918
0644
edit
dl
rm
language.html
13648
0644
edit
dl
rm
linecache.html
13492
0644
edit
dl
rm
locale.html
61540
0644
edit
dl
rm
logging.config.html
85489
0644
edit
dl
rm
logging.handlers.html
112397
0644
edit
dl
rm
logging.html
134850
0644
edit
dl
rm
lzma.html
56484
0644
edit
dl
rm
macpath.html
9257
0644
edit
dl
rm
mailbox.html
157315
0644
edit
dl
rm
mailcap.html
14676
0644
edit
dl
rm
markup.html
19356
0644
edit
dl
rm
marshal.html
18317
0644
edit
dl
rm
math.html
53661
0644
edit
dl
rm
mimetypes.html
31410
0644
edit
dl
rm
misc.html
8123
0644
edit
dl
rm
mm.html
10022
0644
edit
dl
rm
mmap.html
34294
0644
edit
dl
rm
modulefinder.html
18559
0644
edit
dl
rm
modules.html
10914
0644
edit
dl
rm
msilib.html
57205
0644
edit
dl
rm
msvcrt.html
21989
0644
edit
dl
rm
multiprocessing.html
365487
0644
edit
dl
rm
netdata.html
17470
0644
edit
dl
rm
netrc.html
14568
0644
edit
dl
rm
nis.html
11659
0644
edit
dl
rm
nntplib.html
69601
0644
edit
dl
rm
numbers.html
41432
0644
edit
dl
rm
numeric.html
15535
0644
edit
dl
rm
operator.html
81460
0644
edit
dl
rm
optparse.html
249942
0644
edit
dl
rm
os.html
398039
0644
edit
dl
rm
os.path.html
53818
0644
edit
dl
rm
ossaudiodev.html
47947
0644
edit
dl
rm
othergui.html
10256
0644
edit
dl
rm
parser.html
42408
0644
edit
dl
rm
pathlib.html
116726
0644
edit
dl
rm
pdb.html
52661
0644
edit
dl
rm
persistence.html
15281
0644
edit
dl
rm
pickle.html
115052
0644
edit
dl
rm
pickletools.html
17094
0644
edit
dl
rm
pipes.html
15991
0644
edit
dl
rm
pkgutil.html
31878
0644
edit
dl
rm
platform.html
33728
0644
edit
dl
rm
plistlib.html
29290
0644
edit
dl
rm
poplib.html
30940
0644
edit
dl
rm
posix.html
17608
0644
edit
dl
rm
pprint.html
41969
0644
edit
dl
rm
profile.html
71848
0644
edit
dl
rm
pty.html
17594
0644
edit
dl
rm
pwd.html
13098
0644
edit
dl
rm
pyclbr.html
16520
0644
edit
dl
rm
pydoc.html
15991
0644
edit
dl
rm
pyexpat.html
88938
0644
edit
dl
rm
python.html
17133
0644
edit
dl
rm
py_compile.html
15508
0644
edit
dl
rm
queue.html
28199
0644
edit
dl
rm
quopri.html
13858
0644
edit
dl
rm
random.html
60646
0644
edit
dl
rm
re.html
191176
0644
edit
dl
rm
readline.html
42133
0644
edit
dl
rm
reprlib.html
24964
0644
edit
dl
rm
resource.html
36552
0644
edit
dl
rm
rlcompleter.html
14392
0644
edit
dl
rm
runpy.html
26607
0644
edit
dl
rm
sched.html
20034
0644
edit
dl
rm
secrets.html
24734
0644
edit
dl
rm
select.html
62819
0644
edit
dl
rm
selectors.html
35845
0644
edit
dl
rm
shelve.html
28777
0644
edit
dl
rm
shlex.html
48979
0644
edit
dl
rm
shutil.html
74207
0644
edit
dl
rm
signal.html
55064
0644
edit
dl
rm
site.html
32242
0644
edit
dl
rm
smtpd.html
35892
0644
edit
dl
rm
smtplib.html
68433
0644
edit
dl
rm
sndhdr.html
12439
0644
edit
dl
rm
socket.html
196077
0644
edit
dl
rm
socketserver.html
81918
0644
edit
dl
rm
spwd.html
12328
0644
edit
dl
rm
sqlite3.html
161872
0644
edit
dl
rm
ssl.html
266327
0644
edit
dl
rm
stat.html
44722
0644
edit
dl
rm
statistics.html
50050
0644
edit
dl
rm
stdtypes.html
465658
0644
edit
dl
rm
string.html
95262
0644
edit
dl
rm
stringprep.html
18654
0644
edit
dl
rm
struct.html
51100
0644
edit
dl
rm
subprocess.html
141926
0644
edit
dl
rm
sunau.html
31757
0644
edit
dl
rm
superseded.html
13781
0644
edit
dl
rm
symbol.html
8848
0644
edit
dl
rm
symtable.html
26112
0644
edit
dl
rm
sys.html
141670
0644
edit
dl
rm
sysconfig.html
30259
0644
edit
dl
rm
syslog.html
21026
0644
edit
dl
rm
tabnanny.html
12269
0644
edit
dl
rm
tarfile.html
96758
0644
edit
dl
rm
telnetlib.html
30409
0644
edit
dl
rm
tempfile.html
41394
0644
edit
dl
rm
termios.html
18181
0644
edit
dl
rm
test.html
78555
0644
edit
dl
rm
text.html
13786
0644
edit
dl
rm
textwrap.html
37998
0644
edit
dl
rm
threading.html
103464
0644
edit
dl
rm
time.html
79629
0644
edit
dl
rm
timeit.html
45249
0644
edit
dl
rm
tk.html
23299
0644
edit
dl
rm
tkinter.html
82932
0644
edit
dl
rm
tkinter.scrolledtext.html
9957
0644
edit
dl
rm
tkinter.tix.html
51858
0644
edit
dl
rm
tkinter.ttk.html
110673
0644
edit
dl
rm
token.html
22660
0644
edit
dl
rm
tokenize.html
32149
0644
edit
dl
rm
trace.html
29145
0644
edit
dl
rm
traceback.html
57588
0644
edit
dl
rm
tracemalloc.html
101144
0644
edit
dl
rm
tty.html
10540
0644
edit
dl
rm
turtle.html
250367
0644
edit
dl
rm
types.html
37060
0644
edit
dl
rm
typing.html
139175
0644
edit
dl
rm
undoc.html
9181
0644
edit
dl
rm
unicodedata.html
21108
0644
edit
dl
rm
unittest.html
250689
0644
edit
dl
rm
unittest.mock-examples.html
168144
0644
edit
dl
rm
unittest.mock.html
300089
0644
edit
dl
rm
unix.html
11780
0644
edit
dl
rm
urllib.error.html
14474
0644
edit
dl
rm
urllib.html
9566
0644
edit
dl
rm
urllib.parse.html
76334
0644
edit
dl
rm
urllib.request.html
177199
0644
edit
dl
rm
urllib.robotparser.html
17156
0644
edit
dl
rm
uu.html
12209
0644
edit
dl
rm
uuid.html
31957
0644
edit
dl
rm
venv.html
73909
0644
edit
dl
rm
warnings.html
50320
0644
edit
dl
rm
wave.html
29868
0644
edit
dl
rm
weakref.html
65292
0644
edit
dl
rm
webbrowser.html
26901
0644
edit
dl
rm
windows.html
10626
0644
edit
dl
rm
winreg.html
66730
0644
edit
dl
rm
winsound.html
21268
0644
edit
dl
rm
wsgiref.html
94492
0644
edit
dl
rm
xdrlib.html
33751
0644
edit
dl
rm
xml.dom.html
97570
0644
edit
dl
rm
xml.dom.minidom.html
41481
0644
edit
dl
rm
xml.dom.pulldom.html
24214
0644
edit
dl
rm
xml.etree.elementtree.html
135491
0644
edit
dl
rm
xml.html
19261
0644
edit
dl
rm
xml.sax.handler.html
42659
0644
edit
dl
rm
xml.sax.html
25515
0644
edit
dl
rm
xml.sax.reader.html
45869
0644
edit
dl
rm
xml.sax.utils.html
16928
0644
edit
dl
rm
xmlrpc.client.html
71947
0644
edit
dl
rm
xmlrpc.html
8535
0644
edit
dl
rm
xmlrpc.server.html
49195
0644
edit
dl
rm
zipapp.html
45105
0644
edit
dl
rm
zipfile.html
80039
0644
edit
dl
rm
zipimport.html
23052
0644
edit
dl
rm
zlib.html
34557
0644
edit
dl
rm
_dummy_thread.html
9193
0644
edit
dl
rm
_thread.html
22588
0644
edit
dl
rm
__future__.html
15792
0644
edit
dl
rm
__main__.html
9019
0644
edit
dl
rm
Edit:
/usr/share/doc/python3-docs/html/library/tarfile.html
(96758B)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>13.6. tarfile — Read and write tar archive files — Python 3.6.7 documentation</title> <link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <script type="text/javascript" src="../_static/sidebar.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python 3.6.7 documentation" href="../_static/opensearch.xml"/> <link rel="author" title="About these documents" href="../about.html" /> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="copyright" title="Copyright" href="../copyright.html" /> <link rel="next" title="14. File Formats" href="fileformats.html" /> <link rel="prev" title="13.5. zipfile — Work with ZIP archives" href="zipfile.html" /> <link rel="shortcut icon" type="image/png" href="../_static/py.png" /> <link rel="canonical" href="https://docs.python.org/3/library/tarfile.html" /> <script type="text/javascript" src="../_static/copybutton.js"></script> </head><body> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="fileformats.html" title="14. File Formats" accesskey="N">next</a> |</li> <li class="right" > <a href="zipfile.html" title="13.5. zipfile — Work with ZIP archives" accesskey="P">previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="https://www.python.org/">Python</a> »</li> <li> <a href="../index.html">3.6.7 Documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li> <li class="nav-item nav-item-2"><a href="archiving.html" accesskey="U">13. Data Compression and Archiving</a> »</li> <li class="right"> <div class="inline-search" style="display: none" role="search"> <form class="inline-search" action="../search.html" method="get"> <input placeholder="Quick search" type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> <script type="text/javascript">$('.inline-search').show(0);</script> | </li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <div class="section" id="module-tarfile"> <span id="tarfile-read-and-write-tar-archive-files"></span><h1>13.6. <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> — Read and write tar archive files<a class="headerlink" href="#module-tarfile" title="Permalink to this headline">¶</a></h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.6/Lib/tarfile.py">Lib/tarfile.py</a></p> <hr class="docutils" /> <p>The <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> module makes it possible to read and write tar archives, including those using gzip, bz2 and lzma compression. Use the <a class="reference internal" href="zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a> module to read or write <code class="file docutils literal notranslate"><span class="pre">.zip</span></code> files, or the higher-level functions in <a class="reference internal" href="shutil.html#archiving-operations"><span class="std std-ref">shutil</span></a>.</p> <p>Some facts and figures:</p> <ul class="simple"> <li>reads and writes <a class="reference internal" href="gzip.html#module-gzip" title="gzip: Interfaces for gzip compression and decompression using file objects."><code class="xref py py-mod docutils literal notranslate"><span class="pre">gzip</span></code></a>, <a class="reference internal" href="bz2.html#module-bz2" title="bz2: Interfaces for bzip2 compression and decompression."><code class="xref py py-mod docutils literal notranslate"><span class="pre">bz2</span></code></a> and <a class="reference internal" href="lzma.html#module-lzma" title="lzma: A Python wrapper for the liblzma compression library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">lzma</span></code></a> compressed archives if the respective modules are available.</li> <li>read/write support for the POSIX.1-1988 (ustar) format.</li> <li>read/write support for the GNU tar format including <em>longname</em> and <em>longlink</em> extensions, read-only support for all variants of the <em>sparse</em> extension including restoration of sparse files.</li> <li>read/write support for the POSIX.1-2001 (pax) format.</li> <li>handles directories, regular files, hardlinks, symbolic links, fifos, character devices and block devices and is able to acquire and restore file information like timestamp, access permissions and owner.</li> </ul> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.3: </span>Added support for <a class="reference internal" href="lzma.html#module-lzma" title="lzma: A Python wrapper for the liblzma compression library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">lzma</span></code></a> compression.</p> </div> <dl class="function"> <dt id="tarfile.open"> <code class="descclassname">tarfile.</code><code class="descname">open</code><span class="sig-paren">(</span><em>name=None</em>, <em>mode='r'</em>, <em>fileobj=None</em>, <em>bufsize=10240</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.open" title="Permalink to this definition">¶</a></dt> <dd><p>Return a <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> object for the pathname <em>name</em>. For detailed information on <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> objects and the keyword arguments that are allowed, see <a class="reference internal" href="#tarfile-objects"><span class="std std-ref">TarFile Objects</span></a>.</p> <p><em>mode</em> has to be a string of the form <code class="docutils literal notranslate"><span class="pre">'filemode[:compression]'</span></code>, it defaults to <code class="docutils literal notranslate"><span class="pre">'r'</span></code>. Here is a full list of mode combinations:</p> <table border="1" class="docutils"> <colgroup> <col width="29%" /> <col width="71%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">mode</th> <th class="head">action</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'r'</span> <span class="pre">or</span> <span class="pre">'r:*'</span></code></td> <td>Open for reading with transparent compression (recommended).</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'r:'</span></code></td> <td>Open for reading exclusively without compression.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'r:gz'</span></code></td> <td>Open for reading with gzip compression.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'r:bz2'</span></code></td> <td>Open for reading with bzip2 compression.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'r:xz'</span></code></td> <td>Open for reading with lzma compression.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'x'</span></code> or <code class="docutils literal notranslate"><span class="pre">'x:'</span></code></td> <td>Create a tarfile exclusively without compression. Raise an <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> exception if it already exists.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'x:gz'</span></code></td> <td>Create a tarfile with gzip compression. Raise an <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> exception if it already exists.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'x:bz2'</span></code></td> <td>Create a tarfile with bzip2 compression. Raise an <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> exception if it already exists.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'x:xz'</span></code></td> <td>Create a tarfile with lzma compression. Raise an <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> exception if it already exists.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'a'</span> <span class="pre">or</span> <span class="pre">'a:'</span></code></td> <td>Open for appending with no compression. The file is created if it does not exist.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'w'</span> <span class="pre">or</span> <span class="pre">'w:'</span></code></td> <td>Open for uncompressed writing.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'w:gz'</span></code></td> <td>Open for gzip compressed writing.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'w:bz2'</span></code></td> <td>Open for bzip2 compressed writing.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'w:xz'</span></code></td> <td>Open for lzma compressed writing.</td> </tr> </tbody> </table> <p>Note that <code class="docutils literal notranslate"><span class="pre">'a:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'a:bz2'</span></code> or <code class="docutils literal notranslate"><span class="pre">'a:xz'</span></code> is not possible. If <em>mode</em> is not suitable to open a certain (compressed) file for reading, <a class="reference internal" href="#tarfile.ReadError" title="tarfile.ReadError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ReadError</span></code></a> is raised. Use <em>mode</em> <code class="docutils literal notranslate"><span class="pre">'r'</span></code> to avoid this. If a compression method is not supported, <a class="reference internal" href="#tarfile.CompressionError" title="tarfile.CompressionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CompressionError</span></code></a> is raised.</p> <p>If <em>fileobj</em> is specified, it is used as an alternative to a <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> opened in binary mode for <em>name</em>. It is supposed to be at position 0.</p> <p>For modes <code class="docutils literal notranslate"><span class="pre">'w:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'r:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'w:bz2'</span></code>, <code class="docutils literal notranslate"><span class="pre">'r:bz2'</span></code>, <code class="docutils literal notranslate"><span class="pre">'x:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'x:bz2'</span></code>, <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> accepts the keyword argument <em>compresslevel</em> (default <code class="docutils literal notranslate"><span class="pre">9</span></code>) to specify the compression level of the file.</p> <p>For special purposes, there is a second format for <em>mode</em>: <code class="docutils literal notranslate"><span class="pre">'filemode|[compression]'</span></code>. <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> will return a <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> object that processes its data as a stream of blocks. No random seeking will be done on the file. If given, <em>fileobj</em> may be any object that has a <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> method (depending on the <em>mode</em>). <em>bufsize</em> specifies the blocksize and defaults to <code class="docutils literal notranslate"><span class="pre">20</span> <span class="pre">*</span> <span class="pre">512</span></code> bytes. Use this variant in combination with e.g. <code class="docutils literal notranslate"><span class="pre">sys.stdin</span></code>, a socket <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> or a tape device. However, such a <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> object is limited in that it does not allow random access, see <a class="reference internal" href="#tar-examples"><span class="std std-ref">Examples</span></a>. The currently possible modes:</p> <table border="1" class="docutils"> <colgroup> <col width="23%" /> <col width="77%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Mode</th> <th class="head">Action</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'r|*'</span></code></td> <td>Open a <em>stream</em> of tar blocks for reading with transparent compression.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'r|'</span></code></td> <td>Open a <em>stream</em> of uncompressed tar blocks for reading.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'r|gz'</span></code></td> <td>Open a gzip compressed <em>stream</em> for reading.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'r|bz2'</span></code></td> <td>Open a bzip2 compressed <em>stream</em> for reading.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'r|xz'</span></code></td> <td>Open an lzma compressed <em>stream</em> for reading.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'w|'</span></code></td> <td>Open an uncompressed <em>stream</em> for writing.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'w|gz'</span></code></td> <td>Open a gzip compressed <em>stream</em> for writing.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">'w|bz2'</span></code></td> <td>Open a bzip2 compressed <em>stream</em> for writing.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">'w|xz'</span></code></td> <td>Open an lzma compressed <em>stream</em> for writing.</td> </tr> </tbody> </table> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.5: </span>The <code class="docutils literal notranslate"><span class="pre">'x'</span></code> (exclusive creation) mode was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.6: </span>The <em>name</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p> </div> </dd></dl> <dl class="class"> <dt id="tarfile.TarFile"> <em class="property">class </em><code class="descclassname">tarfile.</code><code class="descname">TarFile</code><a class="headerlink" href="#tarfile.TarFile" title="Permalink to this definition">¶</a></dt> <dd><p>Class for reading and writing tar archives. Do not use this class directly: use <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> instead. See <a class="reference internal" href="#tarfile-objects"><span class="std std-ref">TarFile Objects</span></a>.</p> </dd></dl> <dl class="function"> <dt id="tarfile.is_tarfile"> <code class="descclassname">tarfile.</code><code class="descname">is_tarfile</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.is_tarfile" title="Permalink to this definition">¶</a></dt> <dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if <em>name</em> is a tar archive file, that the <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> module can read.</p> </dd></dl> <p>The <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> module defines the following exceptions:</p> <dl class="exception"> <dt id="tarfile.TarError"> <em class="property">exception </em><code class="descclassname">tarfile.</code><code class="descname">TarError</code><a class="headerlink" href="#tarfile.TarError" title="Permalink to this definition">¶</a></dt> <dd><p>Base class for all <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> exceptions.</p> </dd></dl> <dl class="exception"> <dt id="tarfile.ReadError"> <em class="property">exception </em><code class="descclassname">tarfile.</code><code class="descname">ReadError</code><a class="headerlink" href="#tarfile.ReadError" title="Permalink to this definition">¶</a></dt> <dd><p>Is raised when a tar archive is opened, that either cannot be handled by the <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> module or is somehow invalid.</p> </dd></dl> <dl class="exception"> <dt id="tarfile.CompressionError"> <em class="property">exception </em><code class="descclassname">tarfile.</code><code class="descname">CompressionError</code><a class="headerlink" href="#tarfile.CompressionError" title="Permalink to this definition">¶</a></dt> <dd><p>Is raised when a compression method is not supported or when the data cannot be decoded properly.</p> </dd></dl> <dl class="exception"> <dt id="tarfile.StreamError"> <em class="property">exception </em><code class="descclassname">tarfile.</code><code class="descname">StreamError</code><a class="headerlink" href="#tarfile.StreamError" title="Permalink to this definition">¶</a></dt> <dd><p>Is raised for the limitations that are typical for stream-like <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> objects.</p> </dd></dl> <dl class="exception"> <dt id="tarfile.ExtractError"> <em class="property">exception </em><code class="descclassname">tarfile.</code><code class="descname">ExtractError</code><a class="headerlink" href="#tarfile.ExtractError" title="Permalink to this definition">¶</a></dt> <dd><p>Is raised for <em>non-fatal</em> errors when using <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extract()</span></code></a>, but only if <code class="xref py py-attr docutils literal notranslate"><span class="pre">TarFile.errorlevel</span></code><code class="docutils literal notranslate"><span class="pre">==</span> <span class="pre">2</span></code>.</p> </dd></dl> <dl class="exception"> <dt id="tarfile.HeaderError"> <em class="property">exception </em><code class="descclassname">tarfile.</code><code class="descname">HeaderError</code><a class="headerlink" href="#tarfile.HeaderError" title="Permalink to this definition">¶</a></dt> <dd><p>Is raised by <a class="reference internal" href="#tarfile.TarInfo.frombuf" title="tarfile.TarInfo.frombuf"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarInfo.frombuf()</span></code></a> if the buffer it gets is invalid.</p> </dd></dl> <p>The following constants are available at the module level:</p> <dl class="data"> <dt id="tarfile.ENCODING"> <code class="descclassname">tarfile.</code><code class="descname">ENCODING</code><a class="headerlink" href="#tarfile.ENCODING" title="Permalink to this definition">¶</a></dt> <dd><p>The default character encoding: <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> on Windows, the value returned by <a class="reference internal" href="sys.html#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code></a> otherwise.</p> </dd></dl> <p>Each of the following constants defines a tar archive format that the <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> module is able to create. See section <a class="reference internal" href="#tar-formats"><span class="std std-ref">Supported tar formats</span></a> for details.</p> <dl class="data"> <dt id="tarfile.USTAR_FORMAT"> <code class="descclassname">tarfile.</code><code class="descname">USTAR_FORMAT</code><a class="headerlink" href="#tarfile.USTAR_FORMAT" title="Permalink to this definition">¶</a></dt> <dd><p>POSIX.1-1988 (ustar) format.</p> </dd></dl> <dl class="data"> <dt id="tarfile.GNU_FORMAT"> <code class="descclassname">tarfile.</code><code class="descname">GNU_FORMAT</code><a class="headerlink" href="#tarfile.GNU_FORMAT" title="Permalink to this definition">¶</a></dt> <dd><p>GNU tar format.</p> </dd></dl> <dl class="data"> <dt id="tarfile.PAX_FORMAT"> <code class="descclassname">tarfile.</code><code class="descname">PAX_FORMAT</code><a class="headerlink" href="#tarfile.PAX_FORMAT" title="Permalink to this definition">¶</a></dt> <dd><p>POSIX.1-2001 (pax) format.</p> </dd></dl> <dl class="data"> <dt id="tarfile.DEFAULT_FORMAT"> <code class="descclassname">tarfile.</code><code class="descname">DEFAULT_FORMAT</code><a class="headerlink" href="#tarfile.DEFAULT_FORMAT" title="Permalink to this definition">¶</a></dt> <dd><p>The default format for creating archives. This is currently <a class="reference internal" href="#tarfile.GNU_FORMAT" title="tarfile.GNU_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">GNU_FORMAT</span></code></a>.</p> </dd></dl> <div class="admonition seealso"> <p class="first admonition-title">See also</p> <dl class="last docutils"> <dt>Module <a class="reference internal" href="zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a></dt> <dd>Documentation of the <a class="reference internal" href="zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a> standard module.</dd> <dt><a class="reference internal" href="shutil.html#archiving-operations"><span class="std std-ref">Archiving operations</span></a></dt> <dd>Documentation of the higher-level archiving facilities provided by the standard <a class="reference internal" href="shutil.html#module-shutil" title="shutil: High-level file operations, including copying."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shutil</span></code></a> module.</dd> <dt><a class="reference external" href="https://www.gnu.org/software/tar/manual/html_node/Standard.html">GNU tar manual, Basic Tar Format</a></dt> <dd>Documentation for tar archive files, including GNU tar extensions.</dd> </dl> </div> <div class="section" id="tarfile-objects"> <span id="id1"></span><h2>13.6.1. TarFile Objects<a class="headerlink" href="#tarfile-objects" title="Permalink to this headline">¶</a></h2> <p>The <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> object provides an interface to a tar archive. A tar archive is a sequence of blocks. An archive member (a stored file) is made up of a header block followed by data blocks. It is possible to store a file in a tar archive several times. Each archive member is represented by a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object, see <a class="reference internal" href="#tarinfo-objects"><span class="std std-ref">TarInfo Objects</span></a> for details.</p> <p>A <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> object can be used as a context manager in a <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement. It will automatically be closed when the block is completed. Please note that in the event of an exception an archive opened for writing will not be finalized; only the internally used file object will be closed. See the <a class="reference internal" href="#tar-examples"><span class="std std-ref">Examples</span></a> section for a use case.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 3.2: </span>Added support for the context management protocol.</p> </div> <dl class="class"> <dt> <em class="property">class </em><code class="descclassname">tarfile.</code><code class="descname">TarFile</code><span class="sig-paren">(</span><em>name=None</em>, <em>mode='r'</em>, <em>fileobj=None</em>, <em>format=DEFAULT_FORMAT</em>, <em>tarinfo=TarInfo</em>, <em>dereference=False</em>, <em>ignore_zeros=False</em>, <em>encoding=ENCODING</em>, <em>errors='surrogateescape'</em>, <em>pax_headers=None</em>, <em>debug=0</em>, <em>errorlevel=0</em><span class="sig-paren">)</span></dt> <dd><p>All following arguments are optional and can be accessed as instance attributes as well.</p> <p><em>name</em> is the pathname of the archive. <em>name</em> may be a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>. It can be omitted if <em>fileobj</em> is given. In this case, the file object’s <code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code> attribute is used if it exists.</p> <p><em>mode</em> is either <code class="docutils literal notranslate"><span class="pre">'r'</span></code> to read from an existing archive, <code class="docutils literal notranslate"><span class="pre">'a'</span></code> to append data to an existing file, <code class="docutils literal notranslate"><span class="pre">'w'</span></code> to create a new file overwriting an existing one, or <code class="docutils literal notranslate"><span class="pre">'x'</span></code> to create a new file only if it does not already exist.</p> <p>If <em>fileobj</em> is given, it is used for reading or writing data. If it can be determined, <em>mode</em> is overridden by <em>fileobj</em>’s mode. <em>fileobj</em> will be used from position 0.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last"><em>fileobj</em> is not closed, when <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> is closed.</p> </div> <p><em>format</em> controls the archive format. It must be one of the constants <a class="reference internal" href="#tarfile.USTAR_FORMAT" title="tarfile.USTAR_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">USTAR_FORMAT</span></code></a>, <a class="reference internal" href="#tarfile.GNU_FORMAT" title="tarfile.GNU_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">GNU_FORMAT</span></code></a> or <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a> that are defined at module level.</p> <p>The <em>tarinfo</em> argument can be used to replace the default <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> class with a different one.</p> <p>If <em>dereference</em> is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>, add symbolic and hard links to the archive. If it is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, add the content of the target files to the archive. This has no effect on systems that do not support symbolic links.</p> <p>If <em>ignore_zeros</em> is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>, treat an empty block as the end of the archive. If it is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, skip empty (and invalid) blocks and try to get as many members as possible. This is only useful for reading concatenated or damaged archives.</p> <p><em>debug</em> can be set from <code class="docutils literal notranslate"><span class="pre">0</span></code> (no debug messages) up to <code class="docutils literal notranslate"><span class="pre">3</span></code> (all debug messages). The messages are written to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>.</p> <p>If <em>errorlevel</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, all errors are ignored when using <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extract()</span></code></a>. Nevertheless, they appear as error messages in the debug output, when debugging is enabled. If <code class="docutils literal notranslate"><span class="pre">1</span></code>, all <em>fatal</em> errors are raised as <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exceptions. If <code class="docutils literal notranslate"><span class="pre">2</span></code>, all <em>non-fatal</em> errors are raised as <a class="reference internal" href="#tarfile.TarError" title="tarfile.TarError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TarError</span></code></a> exceptions as well.</p> <p>The <em>encoding</em> and <em>errors</em> arguments define the character encoding to be used for reading or writing the archive and how conversion errors are going to be handled. The default settings will work for most users. See section <a class="reference internal" href="#tar-unicode"><span class="std std-ref">Unicode issues</span></a> for in-depth information.</p> <p>The <em>pax_headers</em> argument is an optional dictionary of strings which will be added as a pax global header if <em>format</em> is <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a>.</p> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.2: </span>Use <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> as the default for the <em>errors</em> argument.</p> </div> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.5: </span>The <code class="docutils literal notranslate"><span class="pre">'x'</span></code> (exclusive creation) mode was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.6: </span>The <em>name</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p> </div> </dd></dl> <dl class="classmethod"> <dt id="tarfile.TarFile.open"> <em class="property">classmethod </em><code class="descclassname">TarFile.</code><code class="descname">open</code><span class="sig-paren">(</span><em>...</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.open" title="Permalink to this definition">¶</a></dt> <dd><p>Alternative constructor. The <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> function is actually a shortcut to this classmethod.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.getmember"> <code class="descclassname">TarFile.</code><code class="descname">getmember</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.getmember" title="Permalink to this definition">¶</a></dt> <dd><p>Return a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object for member <em>name</em>. If <em>name</em> can not be found in the archive, <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> is raised.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">If a member occurs more than once in the archive, its last occurrence is assumed to be the most up-to-date version.</p> </div> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.getmembers"> <code class="descclassname">TarFile.</code><code class="descname">getmembers</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.getmembers" title="Permalink to this definition">¶</a></dt> <dd><p>Return the members of the archive as a list of <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> objects. The list has the same order as the members in the archive.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.getnames"> <code class="descclassname">TarFile.</code><code class="descname">getnames</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.getnames" title="Permalink to this definition">¶</a></dt> <dd><p>Return the members as a list of their names. It has the same order as the list returned by <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a>.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.list"> <code class="descclassname">TarFile.</code><code class="descname">list</code><span class="sig-paren">(</span><em>verbose=True</em>, <em>*</em>, <em>members=None</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.list" title="Permalink to this definition">¶</a></dt> <dd><p>Print a table of contents to <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code>. If <em>verbose</em> is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>, only the names of the members are printed. If it is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, output similar to that of <strong class="program">ls -l</strong> is produced. If optional <em>members</em> is given, it must be a subset of the list returned by <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a>.</p> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.5: </span>Added the <em>members</em> parameter.</p> </div> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.next"> <code class="descclassname">TarFile.</code><code class="descname">next</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.next" title="Permalink to this definition">¶</a></dt> <dd><p>Return the next member of the archive as a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object, when <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> is opened for reading. Return <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> if there is no more available.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.extractall"> <code class="descclassname">TarFile.</code><code class="descname">extractall</code><span class="sig-paren">(</span><em>path="."</em>, <em>members=None</em>, <em>*</em>, <em>numeric_owner=False</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.extractall" title="Permalink to this definition">¶</a></dt> <dd><p>Extract all members from the archive to the current working directory or directory <em>path</em>. If optional <em>members</em> is given, it must be a subset of the list returned by <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a>. Directory information like owner, modification time and permissions are set after all members have been extracted. This is done to work around two problems: A directory’s modification time is reset each time a file is created in it. And, if a directory’s permissions do not allow writing, extracting files to it will fail.</p> <p>If <em>numeric_owner</em> is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, the uid and gid numbers from the tarfile are used to set the owner/group for the extracted files. Otherwise, the named values from the tarfile are used.</p> <div class="admonition warning"> <p class="first admonition-title">Warning</p> <p class="last">Never extract archives from untrusted sources without prior inspection. It is possible that files are created outside of <em>path</em>, e.g. members that have absolute filenames starting with <code class="docutils literal notranslate"><span class="pre">"/"</span></code> or filenames with two dots <code class="docutils literal notranslate"><span class="pre">".."</span></code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.5: </span>Added the <em>numeric_owner</em> parameter.</p> </div> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.6: </span>The <em>path</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p> </div> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.extract"> <code class="descclassname">TarFile.</code><code class="descname">extract</code><span class="sig-paren">(</span><em>member</em>, <em>path=""</em>, <em>set_attrs=True</em>, <em>*</em>, <em>numeric_owner=False</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.extract" title="Permalink to this definition">¶</a></dt> <dd><p>Extract a member from the archive to the current working directory, using its full name. Its file information is extracted as accurately as possible. <em>member</em> may be a filename or a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object. You can specify a different directory using <em>path</em>. <em>path</em> may be a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>. File attributes (owner, mtime, mode) are set unless <em>set_attrs</em> is false.</p> <p>If <em>numeric_owner</em> is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, the uid and gid numbers from the tarfile are used to set the owner/group for the extracted files. Otherwise, the named values from the tarfile are used.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">The <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> method does not take care of several extraction issues. In most cases you should consider using the <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> method.</p> </div> <div class="admonition warning"> <p class="first admonition-title">Warning</p> <p class="last">See the warning for <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.2: </span>Added the <em>set_attrs</em> parameter.</p> </div> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.5: </span>Added the <em>numeric_owner</em> parameter.</p> </div> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.6: </span>The <em>path</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p> </div> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.extractfile"> <code class="descclassname">TarFile.</code><code class="descname">extractfile</code><span class="sig-paren">(</span><em>member</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.extractfile" title="Permalink to this definition">¶</a></dt> <dd><p>Extract a member from the archive as a file object. <em>member</em> may be a filename or a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object. If <em>member</em> is a regular file or a link, an <a class="reference internal" href="io.html#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BufferedReader</span></code></a> object is returned. Otherwise, <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> is returned.</p> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.3: </span>Return an <a class="reference internal" href="io.html#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BufferedReader</span></code></a> object.</p> </div> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.add"> <code class="descclassname">TarFile.</code><code class="descname">add</code><span class="sig-paren">(</span><em>name</em>, <em>arcname=None</em>, <em>recursive=True</em>, <em>exclude=None</em>, <em>*</em>, <em>filter=None</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.add" title="Permalink to this definition">¶</a></dt> <dd><p>Add the file <em>name</em> to the archive. <em>name</em> may be any type of file (directory, fifo, symbolic link, etc.). If given, <em>arcname</em> specifies an alternative name for the file in the archive. Directories are added recursively by default. This can be avoided by setting <em>recursive</em> to <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>. If <em>exclude</em> is given, it must be a function that takes one filename argument and returns a boolean value. Depending on this value the respective file is either excluded (<a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>) or added (<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>). If <em>filter</em> is specified it must be a keyword argument. It should be a function that takes a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object argument and returns the changed <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object. If it instead returns <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> the <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object will be excluded from the archive. See <a class="reference internal" href="#tar-examples"><span class="std std-ref">Examples</span></a> for an example.</p> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.2: </span>Added the <em>filter</em> parameter.</p> </div> <div class="deprecated"> <p><span class="versionmodified">Deprecated since version 3.2: </span>The <em>exclude</em> parameter is deprecated, please use the <em>filter</em> parameter instead.</p> </div> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.addfile"> <code class="descclassname">TarFile.</code><code class="descname">addfile</code><span class="sig-paren">(</span><em>tarinfo</em>, <em>fileobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.addfile" title="Permalink to this definition">¶</a></dt> <dd><p>Add the <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object <em>tarinfo</em> to the archive. If <em>fileobj</em> is given, it should be a <a class="reference internal" href="../glossary.html#term-binary-file"><span class="xref std std-term">binary file</span></a>, and <code class="docutils literal notranslate"><span class="pre">tarinfo.size</span></code> bytes are read from it and added to the archive. You can create <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> objects directly, or by using <a class="reference internal" href="#tarfile.TarFile.gettarinfo" title="tarfile.TarFile.gettarinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">gettarinfo()</span></code></a>.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.gettarinfo"> <code class="descclassname">TarFile.</code><code class="descname">gettarinfo</code><span class="sig-paren">(</span><em>name=None</em>, <em>arcname=None</em>, <em>fileobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.gettarinfo" title="Permalink to this definition">¶</a></dt> <dd><p>Create a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object from the result of <a class="reference internal" href="os.html#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a> or equivalent on an existing file. The file is either named by <em>name</em>, or specified as a <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> <em>fileobj</em> with a file descriptor. <em>name</em> may be a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>. If given, <em>arcname</em> specifies an alternative name for the file in the archive, otherwise, the name is taken from <em>fileobj</em>’s <a class="reference internal" href="io.html#io.FileIO.name" title="io.FileIO.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> attribute, or the <em>name</em> argument. The name should be a text string.</p> <p>You can modify some of the <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a>’s attributes before you add it using <a class="reference internal" href="#tarfile.TarFile.addfile" title="tarfile.TarFile.addfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">addfile()</span></code></a>. If the file object is not an ordinary file object positioned at the beginning of the file, attributes such as <a class="reference internal" href="#tarfile.TarInfo.size" title="tarfile.TarInfo.size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">size</span></code></a> may need modifying. This is the case for objects such as <a class="reference internal" href="gzip.html#gzip.GzipFile" title="gzip.GzipFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">GzipFile</span></code></a>. The <a class="reference internal" href="#tarfile.TarInfo.name" title="tarfile.TarInfo.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> may also be modified, in which case <em>arcname</em> could be a dummy string.</p> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.6: </span>The <em>name</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p> </div> </dd></dl> <dl class="method"> <dt id="tarfile.TarFile.close"> <code class="descclassname">TarFile.</code><code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.close" title="Permalink to this definition">¶</a></dt> <dd><p>Close the <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a>. In write mode, two finishing zero blocks are appended to the archive.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarFile.pax_headers"> <code class="descclassname">TarFile.</code><code class="descname">pax_headers</code><a class="headerlink" href="#tarfile.TarFile.pax_headers" title="Permalink to this definition">¶</a></dt> <dd><p>A dictionary containing key-value pairs of pax global headers.</p> </dd></dl> </div> <div class="section" id="tarinfo-objects"> <span id="id2"></span><h2>13.6.2. TarInfo Objects<a class="headerlink" href="#tarinfo-objects" title="Permalink to this headline">¶</a></h2> <p>A <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object represents one member in a <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a>. Aside from storing all required attributes of a file (like file type, size, time, permissions, owner etc.), it provides some useful methods to determine its type. It does <em>not</em> contain the file’s data itself.</p> <p><a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> objects are returned by <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a>’s methods <code class="xref py py-meth docutils literal notranslate"><span class="pre">getmember()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">gettarinfo()</span></code>.</p> <dl class="class"> <dt id="tarfile.TarInfo"> <em class="property">class </em><code class="descclassname">tarfile.</code><code class="descname">TarInfo</code><span class="sig-paren">(</span><em>name=""</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo" title="Permalink to this definition">¶</a></dt> <dd><p>Create a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object.</p> </dd></dl> <dl class="classmethod"> <dt id="tarfile.TarInfo.frombuf"> <em class="property">classmethod </em><code class="descclassname">TarInfo.</code><code class="descname">frombuf</code><span class="sig-paren">(</span><em>buf</em>, <em>encoding</em>, <em>errors</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.frombuf" title="Permalink to this definition">¶</a></dt> <dd><p>Create and return a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object from string buffer <em>buf</em>.</p> <p>Raises <a class="reference internal" href="#tarfile.HeaderError" title="tarfile.HeaderError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">HeaderError</span></code></a> if the buffer is invalid.</p> </dd></dl> <dl class="classmethod"> <dt id="tarfile.TarInfo.fromtarfile"> <em class="property">classmethod </em><code class="descclassname">TarInfo.</code><code class="descname">fromtarfile</code><span class="sig-paren">(</span><em>tarfile</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.fromtarfile" title="Permalink to this definition">¶</a></dt> <dd><p>Read the next member from the <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> object <em>tarfile</em> and return it as a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarInfo.tobuf"> <code class="descclassname">TarInfo.</code><code class="descname">tobuf</code><span class="sig-paren">(</span><em>format=DEFAULT_FORMAT</em>, <em>encoding=ENCODING</em>, <em>errors='surrogateescape'</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.tobuf" title="Permalink to this definition">¶</a></dt> <dd><p>Create a string buffer from a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object. For information on the arguments see the constructor of the <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> class.</p> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 3.2: </span>Use <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> as the default for the <em>errors</em> argument.</p> </div> </dd></dl> <p>A <code class="docutils literal notranslate"><span class="pre">TarInfo</span></code> object has the following public data attributes:</p> <dl class="attribute"> <dt id="tarfile.TarInfo.name"> <code class="descclassname">TarInfo.</code><code class="descname">name</code><a class="headerlink" href="#tarfile.TarInfo.name" title="Permalink to this definition">¶</a></dt> <dd><p>Name of the archive member.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarInfo.size"> <code class="descclassname">TarInfo.</code><code class="descname">size</code><a class="headerlink" href="#tarfile.TarInfo.size" title="Permalink to this definition">¶</a></dt> <dd><p>Size in bytes.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarInfo.mtime"> <code class="descclassname">TarInfo.</code><code class="descname">mtime</code><a class="headerlink" href="#tarfile.TarInfo.mtime" title="Permalink to this definition">¶</a></dt> <dd><p>Time of last modification.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarInfo.mode"> <code class="descclassname">TarInfo.</code><code class="descname">mode</code><a class="headerlink" href="#tarfile.TarInfo.mode" title="Permalink to this definition">¶</a></dt> <dd><p>Permission bits.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarInfo.type"> <code class="descclassname">TarInfo.</code><code class="descname">type</code><a class="headerlink" href="#tarfile.TarInfo.type" title="Permalink to this definition">¶</a></dt> <dd><p>File type. <em>type</em> is usually one of these constants: <code class="xref py py-const docutils literal notranslate"><span class="pre">REGTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">AREGTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">LNKTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">SYMTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">DIRTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">FIFOTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">CONTTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">CHRTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">BLKTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">GNUTYPE_SPARSE</span></code>. To determine the type of a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object more conveniently, use the <code class="docutils literal notranslate"><span class="pre">is*()</span></code> methods below.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarInfo.linkname"> <code class="descclassname">TarInfo.</code><code class="descname">linkname</code><a class="headerlink" href="#tarfile.TarInfo.linkname" title="Permalink to this definition">¶</a></dt> <dd><p>Name of the target file name, which is only present in <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> objects of type <code class="xref py py-const docutils literal notranslate"><span class="pre">LNKTYPE</span></code> and <code class="xref py py-const docutils literal notranslate"><span class="pre">SYMTYPE</span></code>.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarInfo.uid"> <code class="descclassname">TarInfo.</code><code class="descname">uid</code><a class="headerlink" href="#tarfile.TarInfo.uid" title="Permalink to this definition">¶</a></dt> <dd><p>User ID of the user who originally stored this member.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarInfo.gid"> <code class="descclassname">TarInfo.</code><code class="descname">gid</code><a class="headerlink" href="#tarfile.TarInfo.gid" title="Permalink to this definition">¶</a></dt> <dd><p>Group ID of the user who originally stored this member.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarInfo.uname"> <code class="descclassname">TarInfo.</code><code class="descname">uname</code><a class="headerlink" href="#tarfile.TarInfo.uname" title="Permalink to this definition">¶</a></dt> <dd><p>User name.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarInfo.gname"> <code class="descclassname">TarInfo.</code><code class="descname">gname</code><a class="headerlink" href="#tarfile.TarInfo.gname" title="Permalink to this definition">¶</a></dt> <dd><p>Group name.</p> </dd></dl> <dl class="attribute"> <dt id="tarfile.TarInfo.pax_headers"> <code class="descclassname">TarInfo.</code><code class="descname">pax_headers</code><a class="headerlink" href="#tarfile.TarInfo.pax_headers" title="Permalink to this definition">¶</a></dt> <dd><p>A dictionary containing key-value pairs of an associated pax extended header.</p> </dd></dl> <p>A <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object also provides some convenient query methods:</p> <dl class="method"> <dt id="tarfile.TarInfo.isfile"> <code class="descclassname">TarInfo.</code><code class="descname">isfile</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isfile" title="Permalink to this definition">¶</a></dt> <dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the <code class="xref py py-class docutils literal notranslate"><span class="pre">Tarinfo</span></code> object is a regular file.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarInfo.isreg"> <code class="descclassname">TarInfo.</code><code class="descname">isreg</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isreg" title="Permalink to this definition">¶</a></dt> <dd><p>Same as <a class="reference internal" href="#tarfile.TarInfo.isfile" title="tarfile.TarInfo.isfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isfile()</span></code></a>.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarInfo.isdir"> <code class="descclassname">TarInfo.</code><code class="descname">isdir</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isdir" title="Permalink to this definition">¶</a></dt> <dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if it is a directory.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarInfo.issym"> <code class="descclassname">TarInfo.</code><code class="descname">issym</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.issym" title="Permalink to this definition">¶</a></dt> <dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if it is a symbolic link.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarInfo.islnk"> <code class="descclassname">TarInfo.</code><code class="descname">islnk</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.islnk" title="Permalink to this definition">¶</a></dt> <dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if it is a hard link.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarInfo.ischr"> <code class="descclassname">TarInfo.</code><code class="descname">ischr</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.ischr" title="Permalink to this definition">¶</a></dt> <dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if it is a character device.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarInfo.isblk"> <code class="descclassname">TarInfo.</code><code class="descname">isblk</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isblk" title="Permalink to this definition">¶</a></dt> <dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if it is a block device.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarInfo.isfifo"> <code class="descclassname">TarInfo.</code><code class="descname">isfifo</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isfifo" title="Permalink to this definition">¶</a></dt> <dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if it is a FIFO.</p> </dd></dl> <dl class="method"> <dt id="tarfile.TarInfo.isdev"> <code class="descclassname">TarInfo.</code><code class="descname">isdev</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isdev" title="Permalink to this definition">¶</a></dt> <dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if it is one of character device, block device or FIFO.</p> </dd></dl> </div> <div class="section" id="command-line-interface"> <span id="tarfile-commandline"></span><h2>13.6.3. Command-Line Interface<a class="headerlink" href="#command-line-interface" title="Permalink to this headline">¶</a></h2> <div class="versionadded"> <p><span class="versionmodified">New in version 3.4.</span></p> </div> <p>The <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> module provides a simple command-line interface to interact with tar archives.</p> <p>If you want to create a new tar archive, specify its name after the <a class="reference internal" href="#cmdoption-tarfile-c"><code class="xref std std-option docutils literal notranslate"><span class="pre">-c</span></code></a> option and then list the filename(s) that should be included:</p> <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python -m tarfile -c monty.tar spam.txt eggs.txt </pre></div> </div> <p>Passing a directory is also acceptable:</p> <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python -m tarfile -c monty.tar life-of-brian_1979/ </pre></div> </div> <p>If you want to extract a tar archive into the current directory, use the <a class="reference internal" href="#cmdoption-tarfile-e"><code class="xref std std-option docutils literal notranslate"><span class="pre">-e</span></code></a> option:</p> <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python -m tarfile -e monty.tar </pre></div> </div> <p>You can also extract a tar archive into a different directory by passing the directory’s name:</p> <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python -m tarfile -e monty.tar other-dir/ </pre></div> </div> <p>For a list of the files in a tar archive, use the <a class="reference internal" href="#cmdoption-tarfile-l"><code class="xref std std-option docutils literal notranslate"><span class="pre">-l</span></code></a> option:</p> <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python -m tarfile -l monty.tar </pre></div> </div> <div class="section" id="command-line-options"> <h3>13.6.3.1. Command-line options<a class="headerlink" href="#command-line-options" title="Permalink to this headline">¶</a></h3> <dl class="cmdoption"> <dt id="cmdoption-tarfile-l"> <code class="descname">-l</code><code class="descclassname"> <tarfile></code><a class="headerlink" href="#cmdoption-tarfile-l" title="Permalink to this definition">¶</a></dt> <dt id="cmdoption-tarfile-list"> <code class="descname">--list</code><code class="descclassname"> <tarfile></code><a class="headerlink" href="#cmdoption-tarfile-list" title="Permalink to this definition">¶</a></dt> <dd><p>List files in a tarfile.</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-tarfile-c"> <code class="descname">-c</code><code class="descclassname"> <tarfile> <source1> ... <sourceN></code><a class="headerlink" href="#cmdoption-tarfile-c" title="Permalink to this definition">¶</a></dt> <dt id="cmdoption-tarfile-create"> <code class="descname">--create</code><code class="descclassname"> <tarfile> <source1> ... <sourceN></code><a class="headerlink" href="#cmdoption-tarfile-create" title="Permalink to this definition">¶</a></dt> <dd><p>Create tarfile from source files.</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-tarfile-e"> <code class="descname">-e</code><code class="descclassname"> <tarfile> [<output_dir>]</code><a class="headerlink" href="#cmdoption-tarfile-e" title="Permalink to this definition">¶</a></dt> <dt id="cmdoption-tarfile-extract"> <code class="descname">--extract</code><code class="descclassname"> <tarfile> [<output_dir>]</code><a class="headerlink" href="#cmdoption-tarfile-extract" title="Permalink to this definition">¶</a></dt> <dd><p>Extract tarfile into the current directory if <em>output_dir</em> is not specified.</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-tarfile-t"> <code class="descname">-t</code><code class="descclassname"> <tarfile></code><a class="headerlink" href="#cmdoption-tarfile-t" title="Permalink to this definition">¶</a></dt> <dt id="cmdoption-tarfile-test"> <code class="descname">--test</code><code class="descclassname"> <tarfile></code><a class="headerlink" href="#cmdoption-tarfile-test" title="Permalink to this definition">¶</a></dt> <dd><p>Test whether the tarfile is valid or not.</p> </dd></dl> <dl class="cmdoption"> <dt id="cmdoption-tarfile-v"> <code class="descname">-v</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--verbose</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-tarfile-v" title="Permalink to this definition">¶</a></dt> <dd><p>Verbose output.</p> </dd></dl> </div> </div> <div class="section" id="examples"> <span id="tar-examples"></span><h2>13.6.4. Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2> <p>How to extract an entire tar archive to the current working directory:</p> <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tarfile</span> <span class="n">tar</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar.gz"</span><span class="p">)</span> <span class="n">tar</span><span class="o">.</span><span class="n">extractall</span><span class="p">()</span> <span class="n">tar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> </pre></div> </div> <p>How to extract a subset of a tar archive with <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extractall()</span></code></a> using a generator function instead of a list:</p> <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span> <span class="kn">import</span> <span class="nn">tarfile</span> <span class="k">def</span> <span class="nf">py_files</span><span class="p">(</span><span class="n">members</span><span class="p">):</span> <span class="k">for</span> <span class="n">tarinfo</span> <span class="ow">in</span> <span class="n">members</span><span class="p">:</span> <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">tarinfo</span><span class="o">.</span><span class="n">name</span><span class="p">)[</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="s2">".py"</span><span class="p">:</span> <span class="k">yield</span> <span class="n">tarinfo</span> <span class="n">tar</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar.gz"</span><span class="p">)</span> <span class="n">tar</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="n">members</span><span class="o">=</span><span class="n">py_files</span><span class="p">(</span><span class="n">tar</span><span class="p">))</span> <span class="n">tar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> </pre></div> </div> <p>How to create an uncompressed tar archive from a list of filenames:</p> <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tarfile</span> <span class="n">tar</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">)</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">,</span> <span class="s2">"quux"</span><span class="p">]:</span> <span class="n">tar</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">name</span><span class="p">)</span> <span class="n">tar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> </pre></div> </div> <p>The same example using the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement:</p> <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tarfile</span> <span class="k">with</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">)</span> <span class="k">as</span> <span class="n">tar</span><span class="p">:</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">,</span> <span class="s2">"quux"</span><span class="p">]:</span> <span class="n">tar</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">name</span><span class="p">)</span> </pre></div> </div> <p>How to read a gzip compressed tar archive and display some member information:</p> <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tarfile</span> <span class="n">tar</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar.gz"</span><span class="p">,</span> <span class="s2">"r:gz"</span><span class="p">)</span> <span class="k">for</span> <span class="n">tarinfo</span> <span class="ow">in</span> <span class="n">tar</span><span class="p">:</span> <span class="nb">print</span><span class="p">(</span><span class="n">tarinfo</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="s2">"is"</span><span class="p">,</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">size</span><span class="p">,</span> <span class="s2">"bytes in size and is"</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">""</span><span class="p">)</span> <span class="k">if</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">isreg</span><span class="p">():</span> <span class="nb">print</span><span class="p">(</span><span class="s2">"a regular file."</span><span class="p">)</span> <span class="k">elif</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">isdir</span><span class="p">():</span> <span class="nb">print</span><span class="p">(</span><span class="s2">"a directory."</span><span class="p">)</span> <span class="k">else</span><span class="p">:</span> <span class="nb">print</span><span class="p">(</span><span class="s2">"something else."</span><span class="p">)</span> <span class="n">tar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> </pre></div> </div> <p>How to create an archive and reset the user information using the <em>filter</em> parameter in <a class="reference internal" href="#tarfile.TarFile.add" title="tarfile.TarFile.add"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.add()</span></code></a>:</p> <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tarfile</span> <span class="k">def</span> <span class="nf">reset</span><span class="p">(</span><span class="n">tarinfo</span><span class="p">):</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">uid</span> <span class="o">=</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">gid</span> <span class="o">=</span> <span class="mi">0</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">uname</span> <span class="o">=</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">gname</span> <span class="o">=</span> <span class="s2">"root"</span> <span class="k">return</span> <span class="n">tarinfo</span> <span class="n">tar</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar.gz"</span><span class="p">,</span> <span class="s2">"w:gz"</span><span class="p">)</span> <span class="n">tar</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="n">reset</span><span class="p">)</span> <span class="n">tar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> </pre></div> </div> </div> <div class="section" id="supported-tar-formats"> <span id="tar-formats"></span><h2>13.6.5. Supported tar formats<a class="headerlink" href="#supported-tar-formats" title="Permalink to this headline">¶</a></h2> <p>There are three tar formats that can be created with the <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> module:</p> <ul> <li><p class="first">The POSIX.1-1988 ustar format (<a class="reference internal" href="#tarfile.USTAR_FORMAT" title="tarfile.USTAR_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">USTAR_FORMAT</span></code></a>). It supports filenames up to a length of at best 256 characters and linknames up to 100 characters. The maximum file size is 8 GiB. This is an old and limited but widely supported format.</p> </li> <li><p class="first">The GNU tar format (<a class="reference internal" href="#tarfile.GNU_FORMAT" title="tarfile.GNU_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">GNU_FORMAT</span></code></a>). It supports long filenames and linknames, files bigger than 8 GiB and sparse files. It is the de facto standard on GNU/Linux systems. <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> fully supports the GNU tar extensions for long names, sparse file support is read-only.</p> </li> <li><p class="first">The POSIX.1-2001 pax format (<a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a>). It is the most flexible format with virtually no limits. It supports long filenames and linknames, large files and stores pathnames in a portable way. However, not all tar implementations today are able to handle pax archives properly.</p> <p>The <em>pax</em> format is an extension to the existing <em>ustar</em> format. It uses extra headers for information that cannot be stored otherwise. There are two flavours of pax headers: Extended headers only affect the subsequent file header, global headers are valid for the complete archive and affect all following files. All the data in a pax header is encoded in <em>UTF-8</em> for portability reasons.</p> </li> </ul> <p>There are some more variants of the tar format which can be read, but not created:</p> <ul class="simple"> <li>The ancient V7 format. This is the first tar format from Unix Seventh Edition, storing only regular files and directories. Names must not be longer than 100 characters, there is no user/group name information. Some archives have miscalculated header checksums in case of fields with non-ASCII characters.</li> <li>The SunOS tar extended format. This format is a variant of the POSIX.1-2001 pax format, but is not compatible.</li> </ul> </div> <div class="section" id="unicode-issues"> <span id="tar-unicode"></span><h2>13.6.6. Unicode issues<a class="headerlink" href="#unicode-issues" title="Permalink to this headline">¶</a></h2> <p>The tar format was originally conceived to make backups on tape drives with the main focus on preserving file system information. Nowadays tar archives are commonly used for file distribution and exchanging archives over networks. One problem of the original format (which is the basis of all other formats) is that there is no concept of supporting different character encodings. For example, an ordinary tar archive created on a <em>UTF-8</em> system cannot be read correctly on a <em>Latin-1</em> system if it contains non-<em>ASCII</em> characters. Textual metadata (like filenames, linknames, user/group names) will appear damaged. Unfortunately, there is no way to autodetect the encoding of an archive. The pax format was designed to solve this problem. It stores non-ASCII metadata using the universal character encoding <em>UTF-8</em>.</p> <p>The details of character conversion in <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> are controlled by the <em>encoding</em> and <em>errors</em> keyword arguments of the <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> class.</p> <p><em>encoding</em> defines the character encoding to use for the metadata in the archive. The default value is <a class="reference internal" href="sys.html#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code></a> or <code class="docutils literal notranslate"><span class="pre">'ascii'</span></code> as a fallback. Depending on whether the archive is read or written, the metadata must be either decoded or encoded. If <em>encoding</em> is not set appropriately, this conversion may fail.</p> <p>The <em>errors</em> argument defines how characters are treated that cannot be converted. Possible values are listed in section <a class="reference internal" href="codecs.html#error-handlers"><span class="std std-ref">Error Handlers</span></a>. The default scheme is <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> which Python also uses for its file system calls, see <a class="reference internal" href="os.html#os-filenames"><span class="std std-ref">File Names, Command Line Arguments, and Environment Variables</span></a>.</p> <p>In case of <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a> archives, <em>encoding</em> is generally not needed because all the metadata is stored using <em>UTF-8</em>. <em>encoding</em> is only used in the rare cases when binary pax headers are decoded or when strings with surrogate characters are stored.</p> </div> </div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h3><a href="../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">13.6. <code class="docutils literal notranslate"><span class="pre">tarfile</span></code> — Read and write tar archive files</a><ul> <li><a class="reference internal" href="#tarfile-objects">13.6.1. TarFile Objects</a></li> <li><a class="reference internal" href="#tarinfo-objects">13.6.2. TarInfo Objects</a></li> <li><a class="reference internal" href="#command-line-interface">13.6.3. Command-Line Interface</a><ul> <li><a class="reference internal" href="#command-line-options">13.6.3.1. Command-line options</a></li> </ul> </li> <li><a class="reference internal" href="#examples">13.6.4. Examples</a></li> <li><a class="reference internal" href="#supported-tar-formats">13.6.5. Supported tar formats</a></li> <li><a class="reference internal" href="#unicode-issues">13.6.6. Unicode issues</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="zipfile.html" title="previous chapter">13.5. <code class="docutils literal notranslate"><span class="pre">zipfile</span></code> — Work with ZIP archives</a></p> <h4>Next topic</h4> <p class="topless"><a href="fileformats.html" title="next chapter">14. File Formats</a></p> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../bugs.html">Report a Bug</a></li> <li> <a href="https://github.com/python/cpython/blob/3.6/Doc/library/tarfile.rst" rel="nofollow">Show Source </a> </li> </ul> </div> </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="fileformats.html" title="14. File Formats" >next</a> |</li> <li class="right" > <a href="zipfile.html" title="13.5. zipfile — Work with ZIP archives" >previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="https://www.python.org/">Python</a> »</li> <li> <a href="../index.html">3.6.7 Documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li> <li class="nav-item nav-item-2"><a href="archiving.html" >13. Data Compression and Archiving</a> »</li> <li class="right"> <div class="inline-search" style="display: none" role="search"> <form class="inline-search" action="../search.html" method="get"> <input placeholder="Quick search" type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> <script type="text/javascript">$('.inline-search').show(0);</script> | </li> </ul> </div> <div class="footer"> © <a href="../copyright.html">Copyright</a> 2001-2023, Python Software Foundation. <br /> The Python Software Foundation is a non-profit corporation. <a href="https://www.python.org/psf/donations/">Please donate.</a> <br /> Last updated on Dec 18, 2023. <a href="../bugs.html">Found a bug</a>? <br /> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6. </div> </body> </html>
Save
cmd:
run