`tarfile` --- tar アーカイブファイルの読み書き¶

ソースコード: Lib/tarfile.py

tarfile モジュールは、gzip、bz2、および lzma 圧縮されたものを含む、tar アーカイブを読み書きできます。.zip ファイルの読み書きには zipfile モジュールか、あるいは shutil の高水準関数を使用してください。

いくつかの事実と形態:

モジュールが利用可能な場合、gzip、bz2 ならびに lzma で圧縮されたアーカイブを読み書きします。
POSIX.1-1988 (ustar) フォーマットの読み書きをサポートしています。
longname および longlink 拡張を含む GNU tar フォーマットの読み書きをサポートしています。スパースファイルの復元を含む sparse 拡張は読み込みのみサポートしています。
POSIX.1-2001 (pax) フォーマットの読み書きをサポートしています。
ディレクトリ、一般ファイル、ハードリンク、シンボリックリンク、fifo、キャラクターデバイスおよびブロックデバイスを処理します。また、タイムスタンプ、アクセス許可や所有者のようなファイル情報の取得および保存が可能です。

バージョン 3.3 で変更: lzma 圧縮をサポートしました。

tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)¶

パス名 name の TarFile オブジェクトを返します。TarFile オブジェクトと、利用できるキーワード引数に関する詳細な情報については、TarFile オブジェクト節を参照してください。

mode は 'filemode[:compression]' の形式をとる文字列でなければなりません。デフォルトの値は 'r' です。以下に mode のとりうる組み合わせすべてを示します:

mode	action
`'r' または 'r:*'`	圧縮方法に関して透過的に、読み込み用にオープンします (推奨)。
`'r:'`	非圧縮で読み込み用に排他的にオープンします。
`'r:gz'`	gzip 圧縮で読み込み用にオープンします。
`'r:bz2'`	bzip2 圧縮で読み込み用にオープンします。
`'r:xz'`	lzma 圧縮で読み込み用にオープンします。
`'x'` or `'x:'`	圧縮せずに tarfile を排他的に作成します。tarfile が既存の場合 `FileExistsError` 例外を送出します。
`'x:gz'`	gzip 圧縮で tarfile を作成します。tarfile が既存の場合 `FileExistsError` 例外を送出します。
`'x:bz2'`	bzip2 圧縮で tarfile を作成します。tarfile が既存の場合 `FileExistsError` 例外を送出します。
`'x:xz'`	lzma 圧縮で tarfile を作成します。tarfile が既存の場合 `FileExistsError` 例外を送出します。
`'a' または 'a:'`	非圧縮で追記用にオープンします。ファイルが存在しない場合は新たに作成されます。
`'w' または 'w:'`	非圧縮で書き込み用にオープンします。
`'w:gz'`	gzip 圧縮で書き込み用にオープンします。
`'w:bz2'`	bzip2 圧縮で書き込み用にオープンします。
`'w:xz'`	lzma 圧縮で書き込み用にオープンします。

'a:gz'、'a:bz2'、'a:xz' は利用できないことに注意して下さい。もし mode が、ある (圧縮した) ファイルを読み込み用にオープンするのに適していないなら、ReadError が送出されます。これを防ぐには mode 'r' を使って下さい。もし圧縮方式がサポートされていなければ、CompressionError が送出されます。

もし fileobj が指定されていれば、それは name でバイナリモードでオープンされたファイルオブジェクトの代替として使うことができます。そのファイルオブジェクトの位置が 0 であることを前提に動作します。

'w:gz'、'r:gz'、'w:bz2'、'r:bz2', 'x:gz', 'x:bz2' モードの場合、tarfile.open() はファイルの圧縮レベルを指定するキーワード引数 compresslevel (デフォルトは 9) を受け付けます。

'w:xz' および 'x:xz' モードの場合、tarfile.open() はファイルの圧縮レベルを指定するキーワード引数 preset を受け付けます。

特別な目的のために、mode には 2 番目の形式: 'ファイルモード|[圧縮]' があります。この形式を使うと、tarfile.open() が返すのは、データをブロックからなるストリームとして扱う TarFile オブジェクトになります。この場合、ファイルに対してランダムなシークが行えなくなります。fileobj を指定する場合、 read() および write() メソッドを持つ (mode に依存した) 任意のオブジェクトにできます。bufsize にはブロックサイズを指定します。デフォルトは 20 * 512 バイトです。sys.stdin、ソケット file object、あるいはテープデバイスと組み合わせる場合にはこの形式を使ってください。ただし、このような TarFile オブジェクトにはランダムアクセスを行えないという制限があります。使用例節を参照してください。現在可能なモードは以下のとおりです。

モード	動作
`'r\|*'`	tar ブロックの stream を圧縮方法に関して透過的に読み込み用にオープンします。
`'r\|'`	非圧縮 tar ブロックの stream を読み込み用にオープンします。
`'r\|gz'`	gzip 圧縮の stream を読み込み用にオープンします。
`'r\|bz2'`	bzip2 圧縮の stream を読み込み用にオープンします。
`'r\|xz'`	lzma 圧縮の stream を読み込み用にオープンします。
`'w\|'`	非圧縮の stream を書き込み用にオープンします。
`'w\|gz'`	gzip 圧縮の stream を書き込み用にオープンします。
`'w\|bz2'`	bzip2 圧縮の stream を書き込み用にオープンします。
`'w\|xz'`	lzma 圧縮の stream を書き込み用にオープンします。

バージョン 3.5 で変更: 'x' (排他的作成) モードが追加されました。

バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。

class tarfile.TarFile: tar アーカイブを読み書きするためのクラスです。このクラスを直接使わないこと: 代わりに tarfile.open() を使ってください。TarFile オブジェクトを参照してください。

tarfile.is_tarfile(name)¶: もし name が tar アーカイブファイルであり、tarfile モジュールで読み込める場合に True を返します。 name は文字列、ファイルまたは file-like オブジェクトです。

バージョン 3.9 で変更: ファイルおよびファイルライクオブジェクトをサポートしました。

tarfile モジュールは以下の例外を定義しています:

exception tarfile.TarError¶: すべての tarfile 例外のための基本クラスです。

exception tarfile.ReadError¶: tar アーカイブがオープンされた時、tarfile モジュールで操作できないか、あるいは何か無効であるとき送出されます。

exception tarfile.CompressionError¶: 圧縮方法がサポートされていないか、あるいはデータを正しくデコードできない時に送出されます。

exception tarfile.StreamError¶: ストリームのような TarFile オブジェクトで典型的な制限のために送出されます。

exception tarfile.ExtractError¶: TarFile.extract() を使った時に 致命的でない エラーに対して送出されます。ただし TarFile.errorlevel== 2 の場合に限ります。

exception tarfile.HeaderError¶: TarInfo.frombuf() メソッドが取得したバッファーが不正だったときに送出されます。

exception tarfile.FilterError¶

Base class for members refused by filters.

tarinfo¶: Information about the member that the filter refused to extract, as TarInfo.

exception tarfile.AbsolutePathError¶: Raised to refuse extracting a member with an absolute path.

exception tarfile.OutsideDestinationError¶: Raised to refuse extracting a member outside the destination directory.

exception tarfile.SpecialFileError¶: Raised to refuse extracting a special file (e.g. a device or pipe).

exception tarfile.AbsoluteLinkError¶: Raised to refuse extracting a symbolic link with an absolute path.

exception tarfile.LinkOutsideDestinationError¶: Raised to refuse extracting a symbolic link pointing outside the destination directory.

モジュールレベルで以下の定数が利用できます。

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 標準モジュールのドキュメント。
アーカイブ化操作: shutil が提供するより高水準のアーカイブ機能についてのドキュメント。
GNU tar manual, Basic Tar Format: GNU tar 拡張機能を含む、tar アーカイブファイルのためのドキュメント。

TarFile オブジェクト¶

TarFile オブジェクトは、tar アーカイブへのインターフェースを提供します。tar アーカイブは一連のブロックです。アーカイブメンバー (保存されたファイル) は、ヘッダーブロックとそれに続くデータブロックで構成されています。一つの tar アーカイブにファイルを何回も保存することができます。各アーカイブメンバーは、TarInfo オブジェクトで確認できます。詳細については TarInfo オブジェクトを参照してください。

TarFile オブジェクトは with 文のコンテキストマネージャーとして利用できます。with ブロックが終了したときにオブジェクトはクローズされます。例外が発生した時、内部で利用されているファイルオブジェクトのみがクローズされ、書き込み用にオープンされたアーカイブのファイナライズは行われないことに注意してください。使用例節のユースケースを参照してください。

バージョン 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)¶

以下のすべての引数はオプションで、インスタンス属性としてもアクセスできます。

name はアーカイブのパス名です。name は path-like object でも構いません。fileobj が渡された場合は省略可能です。その場合、ファイルオブジェクトに name 属性があれば、それを利用します。

mode は、既存のアーカイブから読み込むための 'r'、既存のアーカイブに追記するための 'a'、既存のファイルがあれば上書きして新しいファイルを作成する 'w' 、あるいは存在しない場合にのみ新しいファイルを作成する 'x' のいずれかです。

fileobj が与えられていれば、それを使ってデータを読み書きします。もしそれが決定できれば、mode は fileobj のモードで上書きされます。fileobj は位置 0 から利用されます。

注釈

TarFile をクローズした時、fileobj はクローズされません。

format はアーカイブの書き込みフォーマットを制御します。モジュールレベルで定義されている、USTAR_FORMAT、GNU_FORMAT、あるいは PAX_FORMAT のいずれかである必要があります。読み出しのときは、1 つのアーカイブに異なるフォーマットが混在していたとしても、フォーマットは自動的に検知されます。

tarinfo 引数を利用して、デフォルトの TarInfo クラスを別のクラスで置き換えることができます。

dereference が False だった場合、シンボリックリンクやハードリンクがアーカイブに追加されます。True だった場合、リンクのターゲットとなるファイルの内容がアーカイブに追加されます。シンボリックリンクをサポートしていないシステムでは効果がありません。

ignore_zeros が False だった場合、空ブロックをアーカイブの終端として扱います。True だった場合、空の (無効な) ブロックをスキップして、可能な限り多くのメンバーを取得しようとします。このオプションは、連結されたり、壊れたアーカイブファイルを扱うときにのみ、意味があります。

debug は 0 (デバッグメッセージ無し) から 3 (全デバッグメッセージ) まで設定できます。このメッセージは sys.stderr に書き込まれます。

errorlevel controls how extraction errors are handled, see the corresponding attribute.

引数 encoding および errors にはアーカイブの読み書きやエラー文字列の変換に使用する文字エンコーディングを指定します。ほとんどのユーザーはデフォルト設定のままで動作します。詳細に関しては Unicode に関する問題節を参照してください。

引数 pax_headers は、オプションの文字列辞書で、format が PAX_FORMAT だった場合に pax グローバルヘッダーに追加されます。

バージョン 3.2 で変更: 引数 errors のデフォルトが 'surrogateescape' になりました。

バージョン 3.5 で変更: 'x' (排他的作成) モードが追加されました。

バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。

classmethod TarFile.open(...)¶: 代替コンストラクターです。モジュールレベルでの tarfile.open() 関数は、実際はこのクラスメソッドへのショートカットです。

TarFile.getmember(name)¶: メンバー name に対する TarInfo オブジェクトを返します。name がアーカイブに見つからなければ、KeyError が送出されます。

注釈

アーカイブ内にメンバーが複数ある場合は、最後に出現するものが最新のバージョンとみなされます。

TarFile.getmembers()¶: TarInfo アーカイブのメンバーをオブジェクトのリストとして返します。このリストはアーカイブ内のメンバーと同じ順番です。

TarFile.getnames()¶: メンバーをその名前のリストを返します。これは getmembers() で返されるリストと同じ順番です。

TarFile.list(verbose=True, *, members=None)¶: 内容の一覧を sys.stdout に出力します。verbose が False の場合、メンバー名のみ表示します。True の場合、 ls -l に似た出力を生成します。オプションの members を与える場合、 getmembers() が返すリストのサブセットである必要があります。

バージョン 3.5 で変更: members 引数が追加されました。.

TarFile.next()¶: TarFile が読み込み用にオープンされている時、アーカイブの次のメンバーを TarInfo オブジェクトとして返します。もしそれ以上利用可能なものがなければ、None を返します。

TarFile.extractall(path=".", members=None, *, numeric_owner=False, filter=None)¶

すべてのメンバーをアーカイブから現在の作業ディレクトリまたは path に抽出します。オプションの members が与えられるときには、getmembers() で返されるリストの一部でなければなりません。所有者、変更時刻、アクセス権限のようなディレクトリ情報はすべてのメンバーが抽出された後にセットされます。これは二つの問題を回避するためです。一つはディレクトリの変更時刻はその中にファイルが作成されるたびにリセットされるということ、もう一つはディレクトリに書き込み許可がなければその中のファイル抽出は失敗してしまうということです。

numeric_owner が True の場合、tarfile の uid と gid 数値が抽出されたファイルのオーナー/グループを設定するために使用されます。False の場合、tarfile の名前付きの値が使用されます。

The filter argument, which was added in Python 3.9.17, specifies how members are modified or rejected before extraction. See Extraction filters for details. It is recommended to set this explicitly depending on which tar features you need to support.

警告

内容を信頼できない tar アーカイブを、事前の内部チェック前に展開してはいけません。ファイルが path の外側に作られる可能性があります。例えば、"/" で始まる絶対パスのファイル名や、2 重ドット ".." で始まるパスのファイル名です。

Set filter='data' to prevent the most dangerous security issues, and read the Extraction filters section for details.

バージョン 3.5 で変更: numeric_owner 引数が追加されました。

バージョン 3.6 で変更: path パラメタが path-like object を受け付けるようになりました。

バージョン 3.9.17 で変更: filter パラメータが追加されました。

TarFile.extract(member, path="", set_attrs=True, *, numeric_owner=False, filter=None)¶

アーカイブからメンバーの完全な名前を使って、現在のディレクトリに展開します。ファイル情報はできる限り正確に展開されます。 member はファイル名もしくは TarInfo オブジェクトです。 path を使って別のディレクトリを指定することもできます。 path は　path-like object でも構いません。set_attrs が false でない限り、ファイルの属性 (所有者、最終更新時刻、モード) は設定されます。

The numeric_owner and filter arguments are the same as for extractall().

注釈

extract() メソッドはいくつかの展開に関する問題を扱いません。ほとんどの場合、extractall() メソッドの利用を考慮するべきです。

警告

extractall() の警告を参してください。

Set filter='data' to prevent the most dangerous security issues, and read the Extraction filters section for details.

バージョン 3.2 で変更: パラメーターに set_attrs を追加しました。

バージョン 3.5 で変更: numeric_owner 引数が追加されました。

バージョン 3.6 で変更: path パラメタが path-like object を受け付けるようになりました。

バージョン 3.9.17 で変更: filter パラメータが追加されました。

TarFile.extractfile(member)¶: アーカイブからメンバーをファイルオブジェクトとして抽出します。 member はファイル名でも TarInfo オブジェクトでも構いません。member が一般ファイルまたはリンクの場合、io.BufferedReader オブジェクトが返されます。存在するそれ以外のメンバーでは、 None が返されます。それ以外の場合、None が返されます。アーカイブに member が存在しない場合は KeyError が送出されます。

バージョン 3.3 で変更: 戻り値が io.BufferedReader オブジェクトになりました。

TarFile.errorlevel: int¶

If errorlevel is 0, errors are ignored when using TarFile.extract() and TarFile.extractall(). Nevertheless, they appear as error messages in the debug output when debug is greater than 0. If 1 (the default), all fatal errors are raised as OSError or FilterError exceptions. If 2, all non-fatal errors are raised as TarError exceptions as well.

Some exceptions, e.g. ones caused by wrong argument types or data corruption, are always raised.

Custom extraction filters should raise FilterError for fatal errors and ExtractError for non-fatal ones.

Note that when an exception is raised, the archive may be partially extracted. It is the user’s responsibility to clean up.

TarFile.extraction_filter¶

バージョン 3.9.17 で追加.

The extraction filter used as a default for the filter argument of extract() and extractall().

The attribute may be None or a callable. String names are not allowed for this attribute, unlike the filter argument to extract().

If extraction_filter is None (the default), calling an extraction method without a filter argument will use the fully_trusted filter for compatibility with previous Python versions.

In Python 3.12+, leaving extraction_filter=None will emit a DeprecationWarning.

In Python 3.14+, leaving extraction_filter=None will cause extraction methods to use the data filter by default.

The attribute may be set on instances or overridden in subclasses. It also is possible to set it on the TarFile class itself to set a global default, although, since it affects all uses of tarfile, it is best practice to only do so in top-level applications or site configuration. To set a global default this way, a filter function needs to be wrapped in staticmethod() to prevent injection of a self argument.

TarFile.add(name, arcname=None, recursive=True, *, filter=None)¶: ファイル name をアーカイブに追加します。 name は、任意のファイルタイプ (ディレクトリ、fifo、シンボリックリンク等)です。 arcname が与えられている場合は、それはアーカイブ内のファイルの代替名を指定します。デフォルトではディレクトリは再帰的に追加されます。これは、 recursive を False に設定すると避けられます。再帰処理はソートされた順序でエントリーを追加します。 filter が与えられた場合、それは TarInfo オブジェクトを引数として受け取り、操作した TarInfo オブジェクトを返す関数でなければなりません。代わりに None を返した場合、 TarInfo オブジェクトはアーカイブから除外されます。使用例にある例を参照してください。

バージョン 3.2 で変更: filter パラメータが追加されました。

バージョン 3.7 で変更: 再帰処理はソートされた順序でエントリーを追加するようになりました。

TarFile.addfile(tarinfo, fileobj=None)¶: TarInfo オブジェクト tarinfo をアーカイブに追加します。fileobj を与える場合、binary file にしなければならず、 tarinfo.size バイトがそれから読まれ、アーカイブに追加されます。TarInfo オブジェクトを直接作成するか、gettarinfo() を使って作成することができます。

TarFile.gettarinfo(name=None, arcname=None, fileobj=None)¶

os.stat() の結果か、既存のファイルに相当するものから、TarInfo オブジェクトを作成します。このファイルは、name で名付けられるか、ファイル記述子を持つ file object fileobj として指定されます。name は:term:path-like object でも構いません。 arcname が与えられた場合、アーカイブ内のファイルに対して代替名を指定します。与えられない場合、名前は fileobj の name 属性 name 属性から取られます。名前はテキスト文字列にしてください。

TarInfo の属性の一部は、addfile() を使用して追加する前に修正できます。ファイルオブジェクトが、ファイルの先頭にある通常のファイルオブジェクトでない場合、 size などの属性は修正が必要かもしれません。これは、 GzipFile などの属性に当てはまります。name も修正できるかもしれず、この場合、arcname はダミーの文字列にすることができます。

バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。

TarFile.close()¶: TarFile をクローズします。書き込みモードでは、完了ゼロブロックが 2 個アーカイブに追加されます。

TarFile.pax_headers¶: pax グローバルヘッダーに含まれる key-value ペアの辞書です。

TarInfo オブジェクト¶

TarInfo オブジェクトは TarFile の一つのメンバーを表します。ファイルに必要なすべての属性 (ファイルタイプ、ファイルサイズ、時刻、アクセス権限、所有者等のような) を保存する他に、そのタイプを決定するのに役に立ついくつかのメソッドを提供します。これにはファイルのデータそのものは 含まれません 。

TarInfo objects are returned by TarFile's methods getmember(), getmembers() and gettarinfo().

Modifying the objects returned by getmember() or getmembers() will affect all subsequent operations on the archive. For cases where this is unwanted, you can use copy.copy() or call the replace() method to create a modified copy in one step.

Several attributes can be set to None to indicate that a piece of metadata is unused or unknown. Different TarInfo methods handle None differently:

The extract() or extractall() methods will ignore the corresponding metadata, leaving it set to a default.
addfile() will fail.
list() will print a placeholder string.

バージョン 3.9.17 で変更: Added replace() and handling of None.

class tarfile.TarInfo(name="")¶: TarInfo オブジェクトを作成します。

classmethod TarInfo.frombuf(buf, encoding, errors)¶

TarInfo オブジェクトを文字列バッファー buf から作成して返します。

バッファーが不正な場合 HeaderError を送出します。

classmethod TarInfo.fromtarfile(tarfile)¶: TarFile オブジェクトの tarfile から、次のメンバーを読み込んで、それを TarInfo オブジェクトとして返します。

TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')¶: TarInfo オブジェクトから文字列バッファーを作成します。引数についての情報は、TarFile クラスのコンストラクターを参照してください。

バージョン 3.2 で変更: 引数 errors のデフォルトが 'surrogateescape' になりました。

TarInfo オブジェクトには以下のデータ属性があります:

TarInfo.name: str¶: アーカイブメンバーの名前。

TarInfo.size: int¶: バイト単位でのサイズ。

TarInfo.mtime: int | float¶: Time of last modification in seconds since the epoch, as in os.stat_result.st_mtime.

バージョン 3.9.17 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.mode: int¶: Permission bits, as for os.chmod().

バージョン 3.9.17 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.type¶: ファイルタイプ。type は通常、定数 REGTYPE、AREGTYPE、LNKTYPE、SYMTYPE、DIRTYPE、FIFOTYPE、CONTTYPE、CHRTYPE、BLKTYPE、あるいは GNUTYPE_SPARSE のいずれかです。TarInfo オブジェクトのタイプをもっと簡単に解決するには、下記の is*() メソッドを使って下さい。

TarInfo.linkname: str¶

リンク先ファイルの名前。これはタイプ LNKTYPE と SYMTYPE の TarInfo オブジェクトにだけ存在します。

For symbolic links (SYMTYPE), the linkname is relative to the directory that contains the link. For hard links (LNKTYPE), the linkname is relative to the root of the archive.

TarInfo.uid: int¶: ファイルメンバーを保存した元のユーザーのユーザー ID。

バージョン 3.9.17 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.gid: int¶: ファイルメンバーを保存した元のユーザーのグループ ID。

バージョン 3.9.17 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.uname: str¶: ファイルメンバーを保存した元のユーザーのユーザー名。

バージョン 3.9.17 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.gname: str¶: ファイルメンバーを保存した元のユーザーのグループ名。

バージョン 3.9.17 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.pax_headers: dict¶: pax 拡張ヘッダーに関連付けられた、key-value ペアの辞書。

TarInfo.replace(name=..., mtime=..., mode=..., linkname=...,

uid=..., gid=..., uname=..., gname=...,

deep=True)

バージョン 3.9.17 で追加.

Return a new copy of the TarInfo object with the given attributes changed. For example, to return a TarInfo with the group name set to 'staff', use:

new_tarinfo = old_tarinfo.replace(gname='staff')

By default, a deep copy is made. If deep is false, the copy is shallow, i.e. pax_headers and any custom attributes are shared with the original TarInfo object.

TarInfo オブジェクトは便利な照会用のメソッドもいくつか提供しています:

TarInfo.isfile()¶: Tarinfo オブジェクトが一般ファイルの場合に、True を返します。

TarInfo.isreg()¶: isfile() と同じです。

TarInfo.isdir()¶: ディレクトリの場合に True を返します。

TarInfo.issym()¶: シンボリックリンクの場合に True を返します。

TarInfo.islnk()¶: ハードリンクの場合に True を返します。

TarInfo.ischr()¶: キャラクターデバイスの場合に True を返します。

TarInfo.isblk()¶: ブロックデバイスの場合に True を返します。

TarInfo.isfifo()¶: FIFO の場合に True を返します。

TarInfo.isdev()¶: キャラクターデバイス、ブロックデバイスあるいは FIFO のいずれかの場合に True を返します。

Extraction filters¶

バージョン 3.9.17 で追加.

The tar format is designed to capture all details of a UNIX-like filesystem, which makes it very powerful. Unfortunately, the features make it easy to create tar files that have unintended -- and possibly malicious -- effects when extracted. For example, extracting a tar file can overwrite arbitrary files in various ways (e.g. by using absolute paths, .. path components, or symlinks that affect later members).

In most cases, the full functionality is not needed. Therefore, tarfile supports extraction filters: a mechanism to limit functionality, and thus mitigate some of the security issues.

参考

PEP 706: Contains further motivation and rationale behind the design.

The filter argument to TarFile.extract() or extractall() can be:

the string 'fully_trusted': Honor all metadata as specified in the archive. Should be used if the user trusts the archive completely, or implements their own complex verification.
the string 'tar': Honor most tar-specific features (i.e. features of UNIX-like filesystems), but block features that are very likely to be surprising or malicious. See tar_filter() for details.
the string 'data': Ignore or block most features specific to UNIX-like filesystems. Intended for extracting cross-platform data archives. See data_filter() for details.
None (default): Use TarFile.extraction_filter.

If that is also None (the default), the 'fully_trusted' filter will be used (for compatibility with earlier versions of Python).

In Python 3.12, the default will emit a DeprecationWarning.

In Python 3.14, the 'data' filter will become the default instead. It's possible to switch earlier; see TarFile.extraction_filter.
A callable which will be called for each extracted member with a TarInfo describing the member and the destination path to where the archive is extracted (i.e. the same path is used for all members):
```
filter(/, member: TarInfo, path: str) -> TarInfo | None
```
The callable is called just before each member is extracted, so it can take the current state of the disk into account. It can:
- return a TarInfo object which will be used instead of the metadata in the archive, or
- return None, in which case the member will be skipped, or
- raise an exception to abort the operation or skip the member, depending on errorlevel. Note that when extraction is aborted, extractall() may leave the archive partially extracted. It does not attempt to clean up.

Default named filters¶

The pre-defined, named filters are available as functions, so they can be reused in custom filters:

tarfile.fully_trusted_filter(/, member, path)¶

Return member unchanged.

This implements the 'fully_trusted' filter.

tarfile.tar_filter(/, member, path)¶

Implements the 'tar' filter.

Strip leading slashes (/ and os.sep) from filenames.
Refuse to extract files with absolute paths (in case the name is absolute even after stripping slashes, e.g. C:/foo on Windows). This raises AbsolutePathError.
Refuse to extract files whose absolute path (after following symlinks) would end up outside the destination. This raises OutsideDestinationError.
Clear high mode bits (setuid, setgid, sticky) and group/other write bits (S_IWOTH).

Return the modified TarInfo member.

tarfile.data_filter(/, member, path)¶

Implements the 'data' filter. In addition to what tar_filter does:

Refuse to extract links (hard or soft) that link to absolute paths, or ones that link outside the destination.

This raises AbsoluteLinkError or LinkOutsideDestinationError.

Note that such files are refused even on platforms that do not support symbolic links.
Refuse to extract device files (including pipes). This raises SpecialFileError.
For regular files, including hard links:
- Set the owner read and write permissions (S_IWUSR).
- Remove the group & other executable permission (S_IXOTH) if the owner doesn’t have it (S_IXUSR).
For other files (directories), set mode to None, so that extraction methods skip applying permission bits.
Set user and group info (uid, gid, uname, gname) to None, so that extraction methods skip setting it.

Return the modified TarInfo member.

Filter errors¶

When a filter refuses to extract a file, it will raise an appropriate exception, a subclass of FilterError. This will abort the extraction if TarFile.errorlevel is 1 or more. With errorlevel=0 the error will be logged and the member will be skipped, but extraction will continue.

Hints for further verification¶

Even with filter='data', tarfile is not suited for extracting untrusted files without prior inspection. Among other issues, the pre-defined filters do not prevent denial-of-service attacks. Users should do additional checks.

Here is an incomplete list of things to consider:

Extract to a new temporary directory to prevent e.g. exploiting pre-existing links, and to make it easier to clean up after a failed extraction.
When working with untrusted data, use external (e.g. OS-level) limits on disk, memory and CPU usage.
Check filenames against an allow-list of characters (to filter out control characters, confusables, foreign path separators, etc.).
Check that filenames have expected extensions (discouraging files that execute when you “click on them”, or extension-less files like Windows special device names).
Limit the number of extracted files, total size of extracted data, filename length (including symlink length), and size of individual files.
Check for files that would be shadowed on case-insensitive filesystems.

Also note that:

Tar files may contain multiple versions of the same file. Later ones are expected to overwrite any earlier ones. This feature is crucial to allow updating tape archives, but can be abused maliciously.
tarfile does not protect against issues with “live” data, e.g. an attacker tinkering with the destination (or source) directory while extraction (or archiving) is in progress.

Supporting older Python versions¶

Extraction filters were added to Python 3.12, and are backported to older versions as security updates. To check whether the feature is available, use e.g. hasattr(tarfile, 'data_filter') rather than checking the Python version.

The following examples show how to support Python versions with and without the feature. Note that setting extraction_filter will affect any subsequent operations.

Fully trusted archive:

my_tarfile.extraction_filter = (lambda member, path: member)
my_tarfile.extractall()

Use the 'data' filter if available, but revert to Python 3.11 behavior ('fully_trusted') if this feature is not available:

my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                       (lambda member, path: member))
my_tarfile.extractall()

Use the 'data' filter; fail if it is not available:

my_tarfile.extractall(filter=tarfile.data_filter)

or:

my_tarfile.extraction_filter = tarfile.data_filter
my_tarfile.extractall()

Use the 'data' filter; warn if it is not available:

if hasattr(tarfile, 'data_filter'):
    my_tarfile.extractall(filter='data')
else:
    # remove this when no longer needed
    warn_the_user('Extracting may be unsafe; consider updating Python')
    my_tarfile.extractall()

Stateful extraction filter example¶

While tarfile's extraction methods take a simple filter callable, custom filters may be more complex objects with an internal state. It may be useful to write these as context managers, to be used like this:

with StatefulFilter() as filter_func:
    tar.extractall(path, filter=filter_func)

Such a filter can be written as, for example:

class StatefulFilter:
    def __init__(self):
        self.file_count = 0

    def __enter__(self):
        return self

    def __call__(self, member, path):
        self.file_count += 1
        return member

    def __exit__(self, *exc_info):
        print(f'{self.file_count} files extracted')

コマンドラインインターフェイス¶

バージョン 3.4 で追加.

tarfile モジュールは、 tar アーカイブを操作するための簡単なコマンドラインインターフェースを提供しています。

tar アーカイブを新規に作成したい場合、-c オプションの後にまとめたいファイル名のリストを指定してください:

$ python -m tarfile -c monty.tar  spam.txt eggs.txt

ディレクトリを渡すこともできます:

$ python -m tarfile -c monty.tar life-of-brian_1979/

tar アーカイブをカレントディレクトリに展開したい場合、-e オプションを使用してください:

$ python -m tarfile -e monty.tar

ディレクトリ名を渡すことで tar アーカイブを別のディレクトリに取り出すこともできます:

$ python -m tarfile -e monty.tar  other-dir/

tar アーカイブ内のファイル一覧を表示するには -l を使用してください:

$ python -m tarfile -l monty.tar

コマンドラインオプション¶

-l <tarfile>¶
--list <tarfile>¶: tarfile 内のファイル一覧を表示します。

-c <tarfile> <source1> ... <sourceN>¶
--create <tarfile> <source1> ... <sourceN>¶: ソースファイルから tarfile を作成します。

-e <tarfile> [<output_dir>]¶
--extract <tarfile> [<output_dir>]¶: output_dir が指定されていない場合、カレントディレクトリに tarfile を展開します。

-t <tarfile>¶
--test <tarfile>¶: tarfile が有効かどうか調べます。

-v, --verbose¶: 詳細も出力します。

--filter <filtername>¶: Specifies the filter for --extract. See Extraction filters for details. Only string names are accepted (that is, fully_trusted, tar, and data).

バージョン 3.9.17 で追加.

使用例¶

tar アーカイブから現在のディレクトリにすべて抽出する方法:

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall()
tar.close()

tar アーカイブの一部を、リストの代わりにジェネレーター関数を利用して TarFile.extractall() で展開する方法:

import os
import tarfile

def py_files(members):
    for tarinfo in members:
        if os.path.splitext(tarinfo.name)[1] == ".py":
            yield tarinfo

tar = tarfile.open("sample.tar.gz")
tar.extractall(members=py_files(tar))
tar.close()

非圧縮 tar アーカイブをファイル名のリストから作成する方法:

import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
    tar.add(name)
tar.close()

with 文を利用した同じ例:

import tarfile
with tarfile.open("sample.tar", "w") as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

gzip 圧縮 tar アーカイブを作成してメンバー情報のいくつかを表示する方法:

import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
    print(tarinfo.name, "is", tarinfo.size, "bytes in size and is ", end="")
    if tarinfo.isreg():
        print("a regular file.")
    elif tarinfo.isdir():
        print("a directory.")
    else:
        print("something else.")
tar.close()

TarFile.add() 関数の filter 引数を利用してユーザー情報をリセットしながらアーカイブを作成する方法:

import tarfile
def reset(tarinfo):
    tarinfo.uid = tarinfo.gid = 0
    tarinfo.uname = tarinfo.gname = "root"
    return tarinfo
tar = tarfile.open("sample.tar.gz", "w:gz")
tar.add("foo", filter=reset)
tar.close()

サポートしている tar フォーマット¶

tarfile モジュールは 3 種類の tar フォーマットを作成することができます:

POSIX.1-1988 ustar format (USTAR_FORMAT). ファイル名の長さは256文字までで、リンク名の長さは100文字までです。最大のファイルサイズは8GiBです。このフォーマットは古くて制限が多いですが、広くサポートされています。
GNU tar format (GNU_FORMAT). 長いファイル名とリンク名、8GiBを超えるファイルやスパース(sparse)ファイルをサポートしています。これは GNU/Linux システムにおいてデファクト・スタンダードになっています。 tarfile モジュールは長いファイル名を完全にサポートしています。スパースファイルは読み込みのみサポートしています。
The POSIX.1-2001 pax format (PAX_FORMAT). 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. Modern tar implementations, including GNU tar, bsdtar/libarchive and star, fully support extended pax features; some old or unmaintained libraries may not, but should treat pax archives as if they were in the universally-supported ustar format. It is the current default format for new archives.

It extends the existing ustar format with 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 UTF-8 for portability reasons.

他にも、読み込みのみサポートしている tar フォーマットがいくつかあります:

ancient V7 フォーマット。これは Unix 7th Edition から存在する、最初の tar フォーマットです。通常のファイルとディレクトリのみ保存します。名前は 100 文字を超えてはならず、ユーザー/グループ名に関する情報は保存されません。いくつかのアーカイブは、フィールドが ASCII でない文字を含む場合に、ヘッダーのチェックサムの計算を誤ります。
SunOS tar 拡張フォーマット。POSIX.1-2001 pax フォーマットの亜流ですが、互換性がありません。

Unicode に関する問題¶

tar フォーマットは、もともとテープドライブにファイルシステムのバックアップをとる目的で設計されました。現在、tarアーカイブはファイルを配布する際に一般的に用いられ、ネットワーク上で交換されています。オリジナルフォーマットが抱える一つの問題は (他の多くのフォーマットでも同じですが)、様々な文字エンコーディングのサポートについて考慮していないことです。例えば、UTF-8 システム上で作成された通常の tar アーカイブは、非 ASCII 文字を含んでいた場合、Latin-1 システムでは正しく読み取ることができません。テキストのメタデータ (ファイル名、リンク名、ユーザー/グループ名など) は破壊されます。残念なことに、アーカイブのエンコーディングを自動検出する方法はありません。pax フォーマットはこの問題を解決するために設計されました。これは非 ASCII メタデータをユニバーサル文字エンコーディング UTF-8 を使用して格納します。

tarfile における文字変換処理の詳細は TarFile クラスのキーワード引数 encoding および errors によって制御されます。

encoding はアーカイブのメタデータに使用する文字エンコーディングを指定します。デフォルト値は sys.getfilesystemencoding() で、フォールバックとして 'ascii' が使用されます。アーカイブの読み書き時に、メタデータはそれぞれデコードまたはエンコードしなければなりません。encoding に適切な値が設定されていない場合、その変換は失敗することがあります。

引数 errors は文字を変換できない時の扱いを指定します。指定できる値はエラーハンドラ節を参照してください。デフォルトのスキームは 'surrogateescape' で、Python はそのファイルシステムの呼び出しも使用します。ファイル名、コマンドライン引数、および環境変数を参照してください。

デフォルトの PAX_FORMAT アーカイブでは、メタデータはすべて UTF-8 で格納されるため、encoding は通常指定する必要はありません。encoding は、まれにある、バイナリの pax ヘッダーがデコードされた場合、あるいはサロゲート文字を含む文字列が格納されていた場合に使用されます。

`tarfile` --- tar アーカイブファイルの読み書き¶

TarFile オブジェクト¶

TarInfo オブジェクト¶

Extraction filters¶

Default named filters¶

Filter errors¶

Hints for further verification¶

Supporting older Python versions¶

Stateful extraction filter example¶

コマンドラインインターフェイス¶

コマンドラインオプション¶

使用例¶

サポートしている tar フォーマット¶

Unicode に関する問題¶

目次

前のトピックへ

次のトピックへ

このページ

tarfile --- tar アーカイブファイルの読み書き¶

TarFile オブジェクト¶

TarInfo オブジェクト¶

Extraction filters¶

Default named filters¶

Filter errors¶

Hints for further verification¶

Supporting older Python versions¶

Stateful extraction filter example¶

コマンドラインインターフェイス¶

コマンドラインオプション¶

使用例¶

サポートしている tar フォーマット¶

Unicode に関する問題¶

`tarfile` --- tar アーカイブファイルの読み書き¶