tarfile --- 讀取與寫入 tar 封存檔案¶
原始碼：Lib/tarfile.py
tarfile 模組用於讀取與寫入 tar 封存檔案，包括使用 gzip、bz2 和 lzma 壓縮的檔案。使用 zipfile 模組來讀取或寫入 .zip 檔案，或使用 shutil 中的更高階函式。
一些事實和數據：
若相對應的模組可用，則可讀取與寫入
gzip、bz2、compression.zstd和lzma壓縮的封存檔。如果你的 CPython 副本中缺少這些選用模組 (optional modules)，請查閱你的發行者（即提供 Python 給你的人）的文件。如果你就是發行者，請參閱 可選模組的需求。
支援 POSIX.1-1988 (ustar) 格式的讀取與寫入。
支援 GNU tar 格式的讀取與寫入，包括 longname 和 longlink 擴充功能，以及所有 sparse 擴充功能變體的唯讀支援，包括還原稀疏檔案 (sparse files)。
支援 POSIX.1-2001 (pax) 格式的讀取與寫入。
處理目錄、一般檔案、硬連結 (hardlinks)、符號連結 (symbolic links)、fifos、字元裝置 (character devices) 和區塊裝置 (block devices)，並能夠取得與還原檔案資訊，如時間戳記、存取權限和擁有者。
在 3.3 版的變更: 新增對 lzma 壓縮的支援。
在 3.12 版的變更: 解壓縮封存檔時會使用篩選器 (filter)，你可以用它來限制一些意外或危險的功能，或是明確表示這些功能是你預期的，而且封存檔是完全可信任的。
在 3.14 版的變更: 將預設解壓縮篩選器設為 data，這會禁止一些危險的功能，例如指向絕對路徑或目的地之外路徑的連結。在此之前，篩選器策略等同於 fully_trusted。
在 3.14 版的變更: 新增對 Zstandard 壓縮的支援（使用 compression.zstd）。
- tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)¶
回傳路徑名稱 name 的
TarFile物件。關於TarFile物件與允許的關鍵字引數的詳細資訊，請參閱 TarFile 物件。mode 必須是
'filemode[:compression]'形式的字串，預設為'r'。以下是所有可能的模式組合：模式
操作
'r'或'r:*'開啟以讀取，自動偵測壓縮格式（建議使用）。
'r:'開啟以讀取未壓縮的檔案。
'r:gz'開啟以讀取 gzip 壓縮的檔案。
'r:bz2'開啟以讀取 bzip2 壓縮的檔案。
'r:xz'開啟以讀取 lzma 壓縮的檔案。
'r:zst'開啟以讀取 Zstandard 壓縮的檔案。
'x'或'x:'建立一個不壓縮的 tarfile（獨佔模式）。如果檔案已存在，則引發
FileExistsError例外。'x:gz'建立一個使用 gzip 壓縮的 tar 檔案。如果檔案已存在則引發
FileExistsError例外。'x:bz2'建立一個使用 bzip2 壓縮的 tar 檔案。如果檔案已存在，則引發
FileExistsError例外。'x:xz'建立一個使用 lzma 壓縮的 tar 檔案。如果檔案已存在，則引發
FileExistsError例外。'x:zst'建立一個使用 Zstandard 壓縮的 tar 檔案。如果檔案已存在，則引發
FileExistsError例外。'a'或'a:'開啟以附加內容且不使用壓縮。如果檔案不存在則建立它。
'w'或'w:'開啟以寫入未壓縮的內容。
'w:gz'開啟以進行 gzip 壓縮寫入。
'w:bz2'開啟以進行 bzip2 壓縮寫入。
'w:xz'開啟以進行 lzma 壓縮寫入。
'w:zst'開啟以進行 Zstandard 壓縮寫入。
請注意
'a:gz'、'a:bz2'或'a:xz'是不可能的。如果 mode 不適合開啟特定（壓縮）檔案以進行讀取，則會引發ReadError。使用 mode'r'可避免此問題。如果不支援某個壓縮方法，則會引發CompressionError。如果指定了 fileobj，則它會被用作 name 以二進位模式開啟的檔案物件 的替代方案。它應該位於位置 0。
對於模式
'w:gz'、'x:gz'、'w|gz'、'w:bz2'、'x:bz2'、'w|bz2'，tarfile.open()接受關鍵字引數 compresslevel（預設為9）來指定檔案的壓縮等級。對於模式
'w:xz'、'x:xz'和'w|xz'，tarfile.open()接受關鍵字引數 preset 來指定檔案的壓縮等級。對於模式
'w:zst'、'x:zst'和'w|zst'，tarfile.open()接受關鍵字引數 level 來指定檔案的壓縮等級。也可以傳遞關鍵字引數 options，提供由CompressionParameter描述的進階 Zstandard 壓縮參數。可以傳遞關鍵字引數 zstd_dict 以提供ZstdDict，這是一個用於改善較小資料量壓縮效果的 Zstandard 字典。對於特殊用途，mode 有第二種格式：
'filemode|[compression]'。tarfile.open()會回傳一個TarFile物件，該物件將其資料作為區塊串流處理。不會對檔案進行隨機尋找。如果提供了 fileobj，它可以是任何具有read()或write()方法（取決於 mode）且能處理位元組的物件。bufsize 指定區塊大小，預設為20 * 512位元組。此變體可與sys.stdin.buffer、socket 檔案物件 或磁帶裝置等結合使用。但是，這樣的TarFile物件受到限制，因為它不允許隨機存取，請參閱 範例。目前可能的模式：模式
操作
'r|*'開啟以讀取 tar 區塊的串流，自動偵測壓縮格式。
'r|'開啟以讀取未壓縮的 tar 區塊串流。
'r|gz'開啟以讀取 gzip 壓縮的串流。
'r|bz2'開啟以讀取 bzip2 壓縮的串流。
'r|xz'開啟以讀取 lzma 壓縮的串流。
'r|zst'開啟以讀取 Zstandard 壓縮的串流。
'w|'開啟以寫入未壓縮的串流。
'w|gz'開啟以寫入 gzip 壓縮的串流。
'w|bz2'開啟以寫入 bzip2 壓縮的串流。
'w|xz'開啟以寫入 lzma 壓縮的串流。
'w|zst'開啟以寫入 Zstandard 壓縮的串流。
在 3.5 版的變更: 新增了
'x'（獨佔建立）模式。在 3.6 版的變更: name 參數接受類路徑物件。
在 3.12 版的變更: compresslevel 關鍵字引數也適用於串流。
在 3.14 版的變更: preset 關鍵字引數也適用於串流。
- class tarfile.TarFile
用於讀取和寫入 tar 封存檔的類別。請勿直接使用此類別：請改用
tarfile.open()。請參閱 TarFile 物件。
- tarfile.is_tarfile(name)¶
如果 name 是一個
tarfile模組可以讀取的 tar 封存檔，則回傳True。name 可以是str、檔案或類檔案物件。在 3.9 版的變更: 對檔案和類檔案物件的支援。
tarfile 模組定義了以下例外：
- exception tarfile.TarError¶
所有
tarfile例外的基底類別。
- exception tarfile.ReadError¶
當開啟的 tar 封存檔無法被
tarfile模組處理或以某種方式無效時引發。
- exception tarfile.CompressionError¶
當壓縮方法不被支援或資料無法正確解碼時引發。
- exception tarfile.ExtractError¶
在使用
TarFile.extract()時針對非致命錯誤引發，但僅限於TarFile.errorlevel== 2時。
- exception tarfile.HeaderError¶
如果
TarInfo.frombuf()得到的緩衝區無效，則引發此例外。
- exception tarfile.AbsolutePathError¶
當拒絕解壓縮具有絕對路徑的成員時引發。
- exception tarfile.OutsideDestinationError¶
當拒絕解壓縮位於目的地目錄之外的成員時引發。
- exception tarfile.SpecialFileError¶
當拒絕解壓縮特殊檔案（例如裝置或管道）時引發。
- exception tarfile.AbsoluteLinkError¶
當拒絕解壓縮具有絕對路徑的符號連結時引發。
- exception tarfile.LinkOutsideDestinationError¶
當拒絕解壓縮指向目的地目錄之外的符號連結時引發。
- exception tarfile.LinkFallbackError¶
當透過解壓縮另一個封存檔成員來模擬連結（硬連結或符號連結）時，如果該成員會被篩選器位置拒絕，則引發此例外。用於拒絕替代成員的例外可作為
BaseException.__context__取得。在 3.14 版被加入.
以下常數可在模組層級使用：
- tarfile.ENCODING¶
預設字元編碼：在 Windows 上為
'utf-8'，否則為sys.getfilesystemencoding()回傳的值。
以下每個常數定義了 tarfile 模組能夠建立的 tar 封存檔格式。詳細資訊請參閱 支援的 tar 格式 一節。
- tarfile.USTAR_FORMAT¶
POSIX.1-1988 (ustar) 格式。
- tarfile.GNU_FORMAT¶
GNU tar 格式。
- tarfile.PAX_FORMAT¶
POSIX.1-2001 (pax) 格式。
- tarfile.DEFAULT_FORMAT¶
建立封存檔的預設格式。目前為
PAX_FORMAT。在 3.8 版的變更: 新封存檔的預設格式已從
GNU_FORMAT變更為PAX_FORMAT。
也參考
zipfile模組zipfile標準模組的文件。- Archiving operations
標準
shutil模組所提供的更高階封存功能的文件。- GNU tar 手冊，基本 Tar 格式
tar 封存檔案的文件，包括 GNU tar 擴充功能。
TarFile 物件¶
TarFile 物件提供一個 tar 封存檔的介面。tar 封存檔是一個區塊序列。一個封存檔成員（一個儲存的檔案）由一個標頭區塊和後續的資料區塊組成。可以在 tar 封存檔中多次儲存一個檔案。每個封存檔成員由一個 TarInfo 物件表示，詳細資訊請參閱 TarInfo 物件。
TarFile 物件可以在 with 陳述式中用作情境管理器。當區塊完成時，它會自動關閉。請注意，如果發生例外，以寫入方式開啟的封存檔將不會被最終化 (finalized)；只有內部使用的檔案物件會被關閉。使用案例請參閱 範例 一節。
在 3.2 版被加入: 新增對情境管理協定的支援。
- class tarfile.TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=1, stream=False)¶
以下所有引數都是可選的，也可以作為實例屬性存取。
name 是封存檔的路徑名稱。name 可以是類路徑物件。如果提供了 fileobj 則可以省略它。在這種情況下，如果檔案物件的
name屬性存在，則會使用該屬性。mode 可以是
'r'以從現有封存檔讀取、'a'以附加資料到現有檔案、'w'以建立新檔案覆蓋現有檔案，或'x'以僅在檔案不存在時建立新檔案。如果提供了 fileobj，它會被用於讀取或寫入資料。如果可以確定，mode 會被 fileobj 的模式覆蓋。fileobj 將從位置 0 開始使用。
備註
當
TarFile關閉時，fileobj 不會被關閉。format 控制寫入時的封存檔格式。它必須是在模組層級定義的常數
USTAR_FORMAT、GNU_FORMAT或PAX_FORMAT之一。讀取時，即使單一封存檔中存在不同格式，格式也會自動偵測。tarinfo 引數可用於將預設的
TarInfo類別替換為不同的類別。如果 dereference 為
False，則將符號連結和硬連結新增到封存檔。如果為True，則將目標檔案的內容新增到封存檔。這在不支援符號連結的系統上沒有效果。如果 ignore_zeros 為
False，則將空區塊視為封存檔的結尾。如果為True，則跳過空的（和無效的）區塊並嘗試取得盡可能多的成員。這僅對讀取串聯或損壞的封存檔有用。debug 可設定從
0（無偵錯訊息）到3（所有偵錯訊息）。訊息會寫入sys.stderr。errorlevel 控制如何處理解壓縮錯誤，請參閱
對應的屬性。encoding 和 errors 引數定義用於讀取或寫入封存檔的字元編碼以及如何處理轉換錯誤。預設設定適用於大多數使用者。深入資訊請參閱 Unicode 議題 一節。
pax_headers 引數是一個可選的字串字典，如果 format 為
PAX_FORMAT，則會作為 pax 全域標頭新增。如果 stream 設為
True，則讀取封存檔時不會快取封存檔中關於檔案的資訊，從而節省記憶體。在 3.2 版的變更: 使用
'surrogateescape'作為 errors 引數的預設值。在 3.5 版的變更: 新增了
'x'（獨佔建立）模式。在 3.6 版的變更: name 參數接受類路徑物件。
在 3.13 版的變更: 新增 stream 參數。
- classmethod TarFile.open(...)¶
替代建構函式。
tarfile.open()函式實際上是此類別方法的捷徑。
- TarFile.getmember(name)¶
回傳成員 name 的
TarInfo物件。如果在封存檔中找不到 name，則引發KeyError。備註
如果一個成員在封存檔中出現多次，則假定其最後一次出現是最新版本。
- TarFile.getnames()¶
以名稱串列的形式回傳成員。其順序與
getmembers()回傳的串列順序相同。
- TarFile.list(verbose=True, *, members=None)¶
將內容表印出到
sys.stdout。如果 verbose 為False，則只印出成員的名稱。如果為True，則產生類似於 ls -l 的輸出。如果提供了可選的 members，它必須是getmembers()回傳串列的子集合。在 3.5 版的變更: 新增 members 參數。
- TarFile.extractall(path='.', members=None, *, numeric_owner=False, filter=None)¶
將所有成員從封存檔解壓縮到目前的工作目錄或目錄 path。如果提供了可選的 members，它必須是
getmembers()回傳串列的子集合。目錄資訊（如擁有者、修改時間和權限）會在所有成員都被解壓縮後設定。這樣做是為了解決兩個問題：每次在目錄中建立檔案時，目錄的修改時間都會被重設。而且，如果目錄的權限不允許寫入，則無法將檔案解壓縮到其中。如果 numeric_owner 為
True，則使用 tar 檔案中的 uid 和 gid 數字來設定解壓縮檔案的擁有者／群組。否則，使用 tar 檔案中的名稱值。filter 引數指定在解壓縮之前如何修改或拒絕
members。詳細資訊請參閱 解壓縮篩選器。建議僅在需要特定 tar 功能時或作為filter='data'以支援預設安全性較低的 Python 版本（3.13 及更低版本）時明確設定此項。警告
切勿在未事先檢查的情況下解壓縮來自不受信任來源的封存檔。
從 Python 3.14 開始，預設值（
data）將防止最危險的安全問題。但是，它不會防止所有意外或不安全的行為。詳細資訊請閱讀 解壓縮篩選器 一節。在 3.5 版的變更: 新增 numeric_owner 參數。
在 3.6 版的變更: path 參數接受類路徑物件。
在 3.12 版的變更: 新增 filter 參數。
在 3.14 版的變更: filter 參數現在預設為
'data'。
- TarFile.extract(member, path='', set_attrs=True, *, numeric_owner=