`shutil` --- 高水準のファイル操作¶

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

shutil モジュールは、ファイルやファイルの集合に対するさまざまな高水準の操作を提供します。特に、ファイルのコピーや削除を行う関数が用意されています。個々のファイルを操作する場合は os モジュールも参照してください。

警告

高水準のファイルコピー関数 (shutil.copy(), shutil.copy2()) でも、ファイルのメタデータの全てをコピーすることはできません。

POSIXプラットフォームでは、これはACLやファイルのオーナー、グループが失われることを意味しています。 Mac OSでは、リソースフォーク(resource fork)やその他のメタデータが利用されません。これは、リソースが失われ、ファイルタイプや生成者コード(creator code)が正しくなくなることを意味しています。 Windowsでは、ファイルオーナー、ACL、代替データストリームがコピーされません。

ディレクトリとファイルの操作¶

shutil.copyfileobj(fsrc, fdst[, length])¶

file-like object fsrc の内容を fdst へコピーします。整数値 length は与えられた場合バッファサイズを表します。特に length が負の場合、コピー元のデータをチャンク単位で繰り返し読み込むことなく、一度にコピーします。デフォルトでは、制御不能なメモリ消費を避けるためにデータはチャンク単位で読み込まれます。 fsrc オブジェクトの現在のファイル位置が0でない場合、現在の位置からファイル終端までの内容のみがコピーされることに注意してください。

copyfileobj() は、コピー完了時にコピー先のストリームがフラッシュされていることを保証 しません。コピー直後にコピー先を読み込みたい場合 (例えば HTTP ストリームからコピーした一時ファイルの内容を読み込む場合) は、読み込む前にファイルに似たオブジェクトの flush() または close() を必ず呼び出してください。

shutil.copyfile(src, dst, *, follow_symlinks=True)¶

src という名前のファイルの内容 (メタデータを含まない) を dst という名前のファイルに、できるだけ効率的な方法でコピーし、dst を返します。 src と dst は path-like object または文字列でパス名を指定します。

dst は完全な対象ファイル名でなければなりません。対象としてディレクトリ名を指定したい場合は copy() を参照してください。 src と dst が同じファイルだった場合、 SameFileError を送出します。

dst は書き込み可能でなければなりません。そうでない場合、 OSError 例外を送出します。 dst がすでに存在する場合、そのファイルは置き換えられます。キャラクタデバイスやブロックデバイスなどの特殊なファイルとパイプをこの関数でコピーすることはできません。

follow_symlinks が偽で src がシンボリックリンクの場合、 src のリンク先をコピーする代わりに新しいシンボリックリンクを作成します。

引数 src, dst を指定して監査イベント shutil.copyfile を送出します。

バージョン 3.3 で変更: 以前は OSError の代わりに IOError が送出されていました。 follow_symlinks 引数が追加されました。 dst を返すようになりました。

バージョン 3.4 で変更: Error の代わりに SameFileError を送出します。後者は前者のサブクラスなのでこの変更は後方互換です。

バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラットフォーム特有の高速なコピーを行うシステムコールが利用されることがあります。プラットフォーム依存の効率的なコピー操作を参照してください。

exception shutil.SpecialFileError¶: copyfile() または copytree() が名前付きパイプをコピーしようとしたときに送出される例外です。

Added in version 2.7.

exception shutil.SameFileError¶: copyfile() のコピー元と先が同じファイルの場合送出されます。

Added in version 3.4.

shutil.copymode(src, dst, *, follow_symlinks=True)¶

パーミッションを src から dst にコピーします。ファイルの内容、オーナー、グループには影響しません。 src と dst は path-like object または文字列でファイルのパス名を指定します。 follow_symlinks が偽で、src および dst がシンボリックリンクの場合、 copymode() は (リンク先ではなく) dst 自体のモードを変更します。この機能は全てのプラットフォームで使えるわけではありません。詳しくは copystat() を参照してください。シンボリックリンクの変更をしようとした時、 copymode() がローカルのプラットフォームでシンボリックリンクを変更できない場合は何もしません。

引数 src, dst を指定して監査イベント shutil.copymode を送出します。

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

shutil.copystat(src, dst, *, follow_symlinks=True)¶

パーミッション、最終アクセス時間、最終変更時間、その他のフラグを src から dst にコピーします。 Linux では、 copystat() は可能なら "拡張属性" もコピーします。ファイルの内容、オーナー、グループには影響しません。 src と dst は path-like object または文字列でファイルのパス名を指定します。

follow_symlinks が偽の場合、 src と dst の両方がシンボリックリンクであれば、 copystat() はリンク先ではなくてシンボリックリンク自体を操作します。 src からシンボリックリンクの情報を読み込み、 dst のシンボリックリンクにその情報を書き込みます。

注釈

すべてのプラットフォームでシンボリックリンクの検査と変更ができるわけではありません。 Python はその機能が利用かどうかを調べる方法を用意しています。

os.chmod in os.supports_follow_symlinks が True の場合 copystat() はシンボリックリンクのパーミッションを変更できます。
os.utime in os.supports_follow_symlinks が True の場合 copystat() はシンボリックリンクの最終アクセス時間と最終変更時間を変更できます。
os.chflags in os.supports_follow_symlinks が True の場合 copystat() はシンボリックリンクのフラグを変更できます。 (os.chflags がないプラットフォームもあります。)

機能の幾つか、もしくは全てが利用できないプラットフォームでシンボリックリンクを変更しようとした場合、 copystat() は可能な限り全てをコピーします。copystat() が失敗を返すことはありません。

より詳しい情報は os.supports_follow_symlinks を参照して下さい。

引数 src, dst を指定して監査イベント shutil.copystat を送出します。

バージョン 3.3 で変更: follow_symlinks 引数と Linux の拡張属性がサポートされました。

shutil.copy(src, dst, *, follow_symlinks=True)¶

ファイル src をファイルまたはディレクトリ dst にコピーします。 src と dst は両方共 path-like object または文字列でなければなりません。 dst がディレクトリを指定している場合、ファイルは dst の中に、 src のベースファイル名を使ってコピーされます。dst が既に存在するファイルを指定している場合、それは置き換えられます。新しく作成したファイルのパスを返します。

follow_symlinks が偽で、 src がシンボリックリンクの場合、 dst はシンボリックリンクとして作成されます。 follow_symlinks が真で src がシンボリックリンクの場合、 dst には src のリンク先のファイルがコピーされます。

copy() はファイルのデータとパーミッションをコピーします。 (os.chmod() を参照) その他の、ファイルの作成時間や変更時間などのメタデータはコピーしません。コピー元のファイルのメタデータを保存したい場合は、 copy2() を利用してください。

引数 src, dst を指定して監査イベント shutil.copyfile を送出します。

引数 src, dst を指定して監査イベント shutil.copymode を送出します。

バージョン 3.3 で変更: follow_symlinks 引数が追加されました。新しく作成されたファイルのパスを返すようになりました。

バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラットフォーム特有の高速なコピーを行うシステムコールが利用されることがあります。プラットフォーム依存の効率的なコピー操作を参照してください。

shutil.copy2(src, dst, *, follow_symlinks=True)¶

copy2() はファイルのメタデータを保持しようとすることを除けば copy() と等価です。

follow_symlinks が偽でかつ src がシンボリックリンクの場合、 copy2() は src シンボリックリンク全てのメタデータを新たに作成される dst シンボリックリンクにコピーしようとします。しかし、この機能は全てのプラットフォームで利用可能なわけではありません。この機能の全部または一部が利用可能でないプラットフォームにおいては、 copy2() は可能な限りのメタデータを保存しようとしますが、一方で copy2()　はメタデータを保存できないことを理由とする例外を送出しません。

copy2() はファイルのメタデータをコピーするために copystat() を利用します。シンボリックリンクのメタデータを変更するためのプラットフォームサポートについては copystat() を参照して下さい。

引数 src, dst を指定して監査イベント shutil.copyfile を送出します。

引数 src, dst を指定して監査イベント shutil.copystat を送出します。

バージョン 3.3 で変更: follow_symlinks 引数が追加されました。拡張ファイルシステム属性もコピーしようと試みます (現在は Linux のみ)。新しく作成されたファイルへのパスを返すようになりました。

バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラットフォーム特有の高速なコピーを行うシステムコールが利用されることがあります。プラットフォーム依存の効率的なコピー操作を参照してください。

shutil.ignore_patterns(*patterns)¶: このファクトリ関数は、 copytree() 関数の ignore 引数に渡すための呼び出し可能オブジェクトを作成します。 glob形式の patterns にマッチするファイルやディレクトリが無視されます。下の例を参照してください。

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)¶

src をルートとするディレクトリツリー全体を dst というディレクトリに再帰的にコピーし、コピー先のディレクトリを返します。デフォルトでは、dst を作成するために必要な途中のディレクトリもすべて作成します。

各ディレクトリのパーミッション、最終アクセス時間、最終変更時間は copystat() でコピーされます。それぞれのファイルは copy2() でコピーされます。

symlinks が真の場合、ソースツリー内のシンボリックリンクは新しいツリーでもシンボリックになり、元のシンボリックリンクのメタデータはプラットフォームが許す限りコピーされます。偽の場合や省略された場合、リンク先のファイルの内容とメタデータが新しいツリーにコピーされます。

symlinks が偽の場合、リンク先のファイルが存在しなければ、コピー処理終了時に送出される Error 例外のエラーリストに例外が追加されます。オプションの ignore_dangling_symlinks フラグを真に設定してこのエラーを送出させないこともできます。このオプションは os.symlink() をサポートしていないプラットフォーム上では効果がないことに注意してください。

ignore は copytree() が走査しているディレクトリと os.listdir() が返すその内容のリストを引数として受け取ることのできる呼び出し可能オブジェクトでなければなりません。 copytree() は再帰的に呼び出されるので、 ignore はコピーされる各ディレクトリ毎に呼び出されます。 ignore の戻り値はカレントディレクトリに相対的なディレクトリ名およびファイル名のシーケンス（すなわち第二引数の項目のサブセット）でなければなりません。それらの名前はコピー中に無視されます。 ignore_patterns() を用いて glob 形式のパターンによって無視する呼び出し可能オブジェクトを作成することが出来ます。

例外が発生した場合、理由のリストとともに Error を送出します。

copy_function は各ファイルをコピーするために利用される呼び出し可能オブジェクトでなければなりません。 copy_function はコピー元のパスとコピー先のパスを引数に呼び出されます。デフォルトでは copy2() が利用されますが、同じシグネチャを持つ関数 (copy() など) ならどれでも利用可能です。

dirs_exist_ok が偽 (デフォルト) で dst がすでに存在する場合は、FileExistsError を送出します。 dirs_exist_ok が真の場合は、既存のディレクトリがあってもコピーを続行し、dst ツリー内のファイルを src ツリー内の対応するファイルで上書きします。

引数 src, dst を指定して監査イベント shutil.copytree を送出します。

バージョン 3.2 で変更: 独自のコピー関数を指定できるよう、copy_function 引数が追加されました。 symlinks が偽の場合にリンク切れのシンボリックリンクによるエラーを抑制できるよう、ignore_dangling_symlinks 引数が追加されました。

バージョン 3.3 で変更: symlinks が偽の場合メタデータをコピーします。 dst を返すようになりました。

バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラットフォーム特有の高速なコピーを行うシステムコールが利用されることがあります。プラットフォーム依存の効率的なコピー操作を参照してください。

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

shutil.rmtree(path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)¶

ディレクトリツリー全体を削除します。 path はディレクトリを指していなければならず、ディレクトリへのシンボリックリンクは指定できません。 ignore_errors が真の場合、削除の失敗によるエラーは無視します。偽または省略された場合は、onexc または onerror で指定したハンドラーを呼び出してエラーを処理します。両方とも省略した場合は例外を呼び出し元に伝播させます。

path がディレクトリへのシンボリックリンクで、末尾にパス区切り文字が付いている場合 (例えば 'link/')、OS がリンクを解決するため、rmtree() はリンク先のディレクトリの内容を削除した後、path 自体の削除に失敗します。 pathlib.Path は末尾の区切り文字を取り除くため、rmtree(Path('link/')) は通常どおりリンクを拒否します。

この関数はディレクトリ記述子への相対パスをサポートしています。

注釈

必要な fd ベースの関数をサポートしているプラットフォームでは、シンボリックリンク攻撃に耐性のあるバージョンの rmtree() がデフォルトで利用されます。それ以外のプラットフォームでは、 rmtree() の実装はシンボリックリンク攻撃の影響を受けます。適当なタイミングと環境で攻撃者はファイルシステム上のシンボリックリンクを操作して、それ以外の方法ではアクセス不可能なファイルを削除することが出来ます。アプリケーションは、どちらのバージョンの rmtree() が利用されているかを知るために関数のデータ属性 rmtree.avoids_symlink_attacks を利用することができます。

onexc を指定する場合、 function, path, excinfo の3つの引数を受け取る呼び出し可能オブジェクトでなければなりません。

最初の引数 function は例外を送出した関数で、プラットフォームや実装によって異なります。二つ目の引数 path は function に渡されたパス名です。三つ目の引数 excinfo は送出された例外です。 onexc が送出した例外は捕捉しません。

非推奨の onerror は onexc と似ていますが、三つ目の引数として sys.exc_info() の戻り値であるタプルを受け取ります。

参考

読み取り専用ファイルを含むディレクトリツリーを削除する例は、rmtree の例を参照してください。

引数 path, dir_fd を指定して監査イベント shutil.rmtree を送出します。

バージョン 3.3 で変更: プラットフォームが fd ベースの関数をサポートする場合に自動的に使用されるシンボリックリンク攻撃に耐性のあるバージョンが追加されました。

バージョン 3.8 で変更: Windows では、ディレクトリへのジャンクションを削除する際にリンク先ディレクトリにあるファイルを削除しなくなりました。

バージョン 3.11 で変更: 引数 dir_fd を追加しました。

バージョン 3.12 で変更: onexc 引数が追加され、onerror は非推奨になりました。

バージョン 3.13 で変更: rmtree() は最上位のパスを除き、FileNotFoundError 例外を無視するようになりました。 OSError と OSError のサブクラス以外の例外は、常に呼び出し元に伝播するようになりました。

rmtree.avoids_symlink_attacks¶: プラットフォームと実装がシンボリックリンク攻撃に耐性のあるバージョンの rmtree() を提供しているかどうかを示します。現在のところ、この属性は fd ベースのディレクトリアクセス関数をサポートしているプラットフォームでのみ真になります。

Added in version 3.3.

shutil.move(src, dst, copy_function=copy2)¶

ファイルまたはディレクトリ (src) を再帰的に別の場所に移動して、移動先を返します。

dst が既存のディレクトリまたはディレクトリへのシンボリックリンクの場合、src はそのディレクトリ内に移動されます。そのディレクトリ内の移動先パスは、あらかじめ存在していてはいけません。

dst がすでに存在し、ディレクトリではない場合、os.rename() の動作に応じて上書きされることがあります。

src と移動先が同じファイルシステム上にある場合、内部では優先的に os.rename() を使います。 os.rename() が OSError で失敗した場合 (例えば、ユーザーに移動先ファイルへの書き込み権限はあるものの、その親ディレクトリへの書き込み権限がない場合) は、copy_function を使う方法に切り替えます。その場合は copy_function で src を移動先にコピーしてから削除します。

シンボリックリンクの場合、src と同じリンク先を指す新しいシンボリックリンクを移動先の中、または移動先そのものとして作成し、src を削除します。

copy_function を指定する場合は、src と移動先の二つの引数を受け取る呼び出し可能オブジェクトでなければなりません。 os.rename() を使えない場合に、src を移動先にコピーするために使われます。移動元がディレクトリなら、copy_function を渡して copytree() を呼び出します。デフォルトの copy_function は copy2() です。 copy_function に copy() を指定すると、メタデータもコピーすることが不可能な場合でも、メタデータのコピーを省いて移動を成功させられます。

引数 src, dst を指定して監査イベント shutil.move を送出します。

バージョン 3.3 で変更: 異なるファイルシステムに対する明示的なシンボリックリンク処理が追加されました。これにより GNU mv の振る舞いに適応するようになります。 dst を返すようになりました。

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

バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラットフォーム特有の高速なコピーを行うシステムコールが利用されることがあります。プラットフォーム依存の効率的なコピー操作を参照してください。

バージョン 3.9 で変更: src と dst が両方とも path-like object を受け付けるようになりました。

shutil.disk_usage(path)¶: 指定されたパスについて、ディスクの利用状況を、名前付きタプル (named tuple) で返します。このタプルには total, used, free という属性があり、それぞれトータル、使用中、空きの容量をバイト単位で示します。 path はファイルまたはディレクトリです。

注釈

Unix ファイルシステムでは、path は マウントされた ファイルシステムのパーティション内のパスを指していなければなりません。これらのプラットフォームでは、CPython はマウントされていないファイルシステムのディスク使用量を取得しようとしません。

Added in version 3.3.

バージョン 3.8 で変更: Windowsにおいても path にディレクトリだけでなくファイルを指定できるようになりました。

利用可能な環境: Unix, Windows.

shutil.chown(path, user=None, group=None, *, dir_fd=None, follow_symlinks=True)¶

指定された path のオーナー user と/または group を変更します。

user はシステムのユーザー名か uid です。 group も同じです。少なくともどちらかの引数を指定する必要があります。

内部で利用している os.chown() も参照してください。

引数 path, user, group を指定して監査イベント shutil.chown を送出します。

利用可能な環境: Unix.

Added in version 3.3.

バージョン 3.13 で変更: 引数 dir_fd および follow_symlinks が追加されました。

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)¶

cmd を実行しようとした時に実行される実行ファイルのパスを返します。 cmd を呼び出せない場合は None を返します。

mode は os.access() に渡すパーミッションマスクで、デフォルトではファイルが存在して実行可能であることを確認します。

path は検索するディレクトリを os.pathsep で区切って指定する「PATH 文字列」です。 path を指定しない場合は os.environ から環境変数 PATH を読み取り、それも設定されていなければ os.defpath を使います。

cmd にディレクトリ部分が含まれている場合、which() は指定されたパスだけを直接調べ、path やシステムの PATH 環境変数に列挙されたディレクトリは検索しません。

Windows では、mode に os.X_OK が含まれていない場合、カレントディレクトリを path の先頭に追加します。 mode に os.X_OK が含まれている場合は、Windows API の NeedCurrentDirectoryForExePathW に問い合わせて、カレントディレクトリを path の先頭に追加するかどうか決めます。実行ファイルを探す際にカレントディレクトリを調べないようにするには、環境変数 NoDefaultCurrentDirectoryInExePath を設定してください。

Windows ではさらに、拡張子が指定されていないコマンドを解決するために PATHEXT 環境変数を使います。例えば shutil.which("python") を呼び出すと、which() は PATHEXT を調べて、path 内のディレクトリで python.exe を探すべきだと判断します。 Windows での例を示します。

>>> shutil.which("python")
'C:\\Python33\\python.EXE'

cmd がディレクトリ部分を含むパスである場合にも、この処理が適用されます。

>>> shutil.which("C:\\Python33\\python")
'C:\\Python33\\python.EXE'

Added in version 3.3.

バージョン 3.8 で変更: bytes 型も使用できるようになりました。 cmd が bytes 型の場合、戻り値も bytes 型です。

バージョン 3.12 で変更: Windows では、mode に os.X_OK が含まれ、WinAPI の NeedCurrentDirectoryForExePathW(cmd) が偽の場合、カレントディレクトリを検索パスの先頭に追加しなくなりました。それ以外の場合は、カレントディレクトリがすでに検索パスに含まれていても先頭に追加します。 cmd にディレクトリ部分が含まれている場合や、PATHEXT に含まれる拡張子で終わる場合にも PATHEXT を使うようになりました。また、拡張子のないファイル名も見つけられるようになりました。

exception shutil.Error¶: 複数ファイルの操作中に発生した例外をまとめる OSError のサブクラスです。 copytree() の場合、例外の引数は 3 要素のタプル (srcname、dstname、exception) のリストです。

プラットフォーム依存の効率的なコピー操作¶

Python 3.8 から、ファイルのコピーを伴う全ての関数 (copyfile(), copy(), copy2(), copytree(), および move()) はより効率的なファイルのコピーのためにプラットフォーム特有の "高速なコピー" を行うことがあります (bpo-33671 を参照してください). ここで "高速なコピー" とは、 "outfd.write(infd.read())" のようにPython が管理するユーザー空間のバッファを利用することを避け、コピー操作がカーネル空間内で行われることを意味します。

macOS では fcopyfile がファイルの内容（メタデータを除く）をコピーするために利用されます。

Linux では os.copy_file_range() または os.sendfile() が利用されます。

Solaris では os.sendfile() が利用されます。

Windows では shutil.copyfile() のデフォルトのバッファサイズを大きくして (64 KiB ではなく 1 MiB)、memoryview() を使う shutil.copyfileobj() の変種を利用します。この方法でも読み書きはループで行います。 Windows の shutil.copy2() はネイティブの CopyFile2 呼び出しを使います。これは最も効率的な方法で、コピーオンライトに対応し、メタデータも保持します。

高速なコピー操作が失敗し、コピー先ファイルにまだデータを書き込んでいない場合、shutil は内部で、通知せずに効率の劣る copyfileobj() 関数へ切り替えます。

バージョン 3.8 で変更.

バージョン 3.14 で変更: Solaris では os.sendfile() を使うようになりました。

バージョン 3.14 で変更: 対応する Linux ファイルシステムでは、os.copy_file_range() を介してコピーオンライトやサーバー側のコピーが内部で使われる場合があります。

copytree の例¶

ignore_patterns() ヘルパ関数を利用する例です:

from shutil import copytree, ignore_patterns

copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

この例では、 .pyc ファイルと、 tmp で始まる全てのファイルやディレクトリを除いて、全てをコピーします。

ignore 引数にロギングさせる別の例です。

from shutil import copytree
import logging

def _logpath(path, names):
    logging.info('Working in %s', path)
    return []   # 何も無視しない

copytree(source, destination, ignore=_logpath)

rmtree の例¶

この例は、Windows で読み取り専用ビットが設定されたファイルを含むディレクトリツリーを削除する方法を示します。 onexc コールバックで読み取り専用ビットを解除し、削除を再試行します。その後に発生したエラーは呼び出し元に伝播します。

import os, stat
import shutil

def remove_readonly(func, path, _):
    "読み取り専用ビットを解除して削除を再試行する"
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree(directory, onexc=remove_readonly)

アーカイブ化操作¶

Added in version 3.2.

バージョン 3.5 で変更: xztar 形式のサポートが追加されました。

圧縮とアーカイブ化されているファイルの読み書きの高水準なユーティリティも提供されています。これらは zipfile 、 tarfile モジュールに依拠しています。

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])¶

アーカイブファイル (zip や tar) を作成してその名前を返します。

base_name は、作成するファイルの名前をパスを含めて指定する文字列または path-like object です。形式固有の拡張子は含めません。

format はアーカイブ形式で、"zip" (zlib モジュールを利用できる場合)、"tar"、"gztar" (zlib モジュールを利用できる場合)、"bztar" (bz2 モジュールを利用できる場合)、"xztar" (lzma モジュールを利用できる場合)、"zstdtar" (compression.zstd モジュールを利用できる場合) のいずれかです。

root_dir は、アーカイブのルートディレクトリを指定する文字列または path-like object です。アーカイブ内のすべてのパスはこのディレクトリからの相対パスになります。例えば、通常はアーカイブの作成前に root_dir に移動します。

base_dir は、アーカイブ化を開始するディレクトリを指定する文字列または path-like object です。つまり、アーカイブ内のすべてのファイルやディレクトリのパスに共通する先頭部分になります。 base_dir は root_dir からの相対パスで指定しなければなりません。両者を組み合わせる方法は base_dir を使ったアーカイブ化の例を参照してください。

root_dir と base_dir のどちらも、デフォルトはカレントディレクトリです。

dry_run が真の場合、アーカイブは作成されませんが実行される操作は logger に記録されます。

owner と group は、tar アーカイブを作成するときに使われます。デフォルトでは、カレントのオーナーとグループを使います。

logger は PEP 282 に互換なオブジェクトでなければなりません。これは普通は logging.Logger のインスタンスです。

verbose 引数は使用されず、非推奨です。

引数 base_name, format, root_dir, base_dir を指定して監査イベント shutil.make_archive を送出します。

注釈

register_archive_format() で登録した独自のアーカイバーが root_dir 引数に対応していない場合、この関数はスレッドセーフではありません。その場合、アーカイブ化のためにプロセスのカレントディレクトリを一時的に root_dir に変更します。

バージョン 3.8 で変更: format="tar" で作成されたアーカイブでは、レガシーなGNU形式に代わってモダンな pax (POSIX.1-2001) 形式が使われます。

バージョン 3.10.6 で変更: 標準の .zip アーカイブと tar アーカイブを作成する場合、この関数はスレッドセーフになりました。

バージョン 3.15 で変更: base_name、root_dir、base_dir が path-like object を受け付けるようになりました。

shutil.get_archive_formats()¶

アーカイブ化をサポートしているフォーマットのリストを返します。返されるシーケンスのそれぞれの要素は、タプル (name, description) です。

デフォルトで shutil は以下の形式を提供します。

zip: ZIP ファイル (zlib モジュールが利用可能な場合)。
tar: 非圧縮の tar ファイル。 POSIX.1-2001 pax 形式が使われます。
gztar: gzip で圧縮された tar ファイル (zlib モジュールが利用可能な場合)。
bztar: bzip2 で圧縮された tar ファイル (bz2 モジュールが利用可能な場合)。
xztar: xz で圧縮された tar ファイル (lzma モジュールが利用可能な場合)。
zstdtar: Zstandard で圧縮された tar ファイル (compression.zstd モジュールが利用可能な場合)。

register_archive_format() を使って、新しいフォーマットを登録したり、既存のフォーマットに独自のアーカイバを提供したりできます。

shutil.register_archive_format(name, function[, extra_args[, description]])¶

アーカイバをフォーマット name に登録します。

function はアーカイブの作成に使う呼び出し可能オブジェクトです。作成するファイルの base_name と、アーカイブ化を開始する base_dir (デフォルトは os.curdir) を順に受け取ります。さらに、make_archive() に渡された owner、group、dry_run、logger がキーワード引数として渡されます。

function の独自の属性 function.supports_root_dir が True の場合、root_dir 引数がキーワード引数として渡されます。それ以外の場合は、function を呼び出す前にプロセスのカレントディレクトリを一時的に root_dir に変更します。この場合、make_archive() はスレッドセーフではありません。

extra_args は、与えられた場合、 (name, value) の対のシーケンスで、アーカイバ呼び出し可能オブジェクトが使われるときに追加のキーワード引数として使われます。

description は、アーカイバのリストを返す get_archive_formats() で使われます。デフォルトでは空の文字列です。

バージョン 3.12 で変更: root_dir 引数を受け取る関数への対応が追加されました。

shutil.unregister_archive_format(name)¶: アーカイブフォーマット name を、サポートされているフォーマットのリストから取り除きます。

shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])¶

アーカイブをアンパックします。 filename はアーカイブのフルパスです。

extract_dir はアーカイブをアンパックする先のディレクトリ名です。指定されなかった場合は現在の作業ディレクトリを利用します。

format はアーカイブフォーマットで、 "zip", "tar", "gztar", "bztar", "xztar", "zstdtar" あるいは register_unpack_format() で登録したその他のフォーマットのどれかです。指定されなかった場合、 unpack_archive() はアーカイブファイル名の拡張子に対して登録されたアンパッカーを利用します。アンパッカーが見つからなかった場合、 ValueError を発生させます。

キーワード専用引数 filter は、内部で使う展開関数に渡されます。 zip ファイルでは filter を指定できません。 tar ファイルでは、tar や Unix 系ファイルシステムに固有の機能を使う場合を除き、'data' (Python 3.14 以降のデフォルト) を使うことをお勧めします (詳細は展開フィルターを参照)。

引数 filename, extract_dir, format を指定して監査イベント shutil.unpack_archive を送出します。

警告

信頼できない提供元のアーカイブは、事前に内容を調べずに展開しないでください。例えば、絶対パスのファイル名や ".." を含むファイル名のメンバーがあると、extract_dir 引数で指定したパスの外にファイルが作成される可能性があります。

Python 3.14 以降、組み込みの両形式 (zip ファイルと tar ファイル) のデフォルト設定は、この種のセキュリティ問題のうち最も危険なものを防ぎますが、意図しない動作を すべて 防ぐわけではありません。 tar 固有の詳細は追加の検証のヒント節を参照してください。

バージョン 3.7 で変更: filename と extract_dir が path-like object を受け付けるようになりました。

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

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])¶

アンパック用のフォーマットを登録します。 name はフォーマット名で、 extensions はそのフォーマットに対応する拡張子 (例えば Zip ファイルに対して .zip) のリストです。

function はアーカイブの展開に使う呼び出し可能オブジェクトです。以下の引数を受け取ります。

アーカイブのパス (位置引数)。
アーカイブの展開先ディレクトリ (位置引数)。
unpack_archive() に指定されていれば、filter キーワード引数。
extra_args に (name, value) タプルのシーケンスとして指定された追加のキーワード引数。

フォーマットの説明として description を指定することができます。これは get_unpack_formats() 関数によって返されます。

shutil.unregister_unpack_format(name)¶: アンパックフォーマットを登録解除します。 name はフォーマットの名前です。

shutil.get_unpack_formats()¶

登録されているすべてのアンパックフォーマットをリストで返します。戻り値のリストの各要素は (name, extensions, description) の形のタプルです。

デフォルトで shutil は以下の形式を提供します。

zip: ZIP ファイル (対応するモジュールが利用可能な場合にのみ圧縮ファイルはアンパックされます)。
tar: 圧縮されていない tar ファイル。
gztar: gzip で圧縮された tar ファイル (zlib モジュールが利用可能な場合)。
bztar: bzip2 で圧縮された tar ファイル (bz2 モジュールが利用可能な場合)。
xztar: xz で圧縮された tar ファイル (lzma モジュールが利用可能な場合)。
zstdtar: Zstandard で圧縮された tar ファイル (compression.zstd モジュールが利用可能な場合)。

register_unpack_format() を使って新しいフォーマットや既存のフォーマットに対する別のアンパッカーを登録することができます。

アーカイブ化の例¶

この例では、ユーザの .ssh ディレクトリにあるすべてのファイルを含む、 gzip された tar ファイルアーカイブを作成します:

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
>>> make_archive(archive_name, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'

結果のアーカイブは、以下のものを含みます:

$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
-rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
-rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
-rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
-rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
-rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
-rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
-rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts

base_dir を使ったアーカイブ化の例¶

この例では、上記の例と同じく make_archive() の使い方を示しますが、ここでは特に base_dir の使い方を説明します。以下のようなディレクトリ構造があるとします。

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── please_add.txt
        └── do_not_add.txt

作成するアーカイブには please_add.txt が含まれますが、いっぽう do_not_add.txt は含まないようにします。この場合以下のようにします。

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> make_archive(
...     archive_name,
...     'tar',
...     root_dir='tmp/root',
...     base_dir='structure/content',
... )
'/Users/tarek/myarchive.tar'

アーカイブに含まれるファイルをリストすると、以下のようになります。

$ python -m tarfile -l /Users/tarek/myarchive.tar
structure/content/
structure/content/please_add.txt

出力ターミナルのサイズの取得¶

shutil.get_terminal_size(fallback=(columns, lines))¶

ターミナルウィンドウのサイズを取得します。

幅と高さについて、それぞれ COLUMNS と LINES という環境変数をチェックします。その変数が定義されていて値が正の整数であればそれを利用します。

典型的な COLUMNS や LINES が定義されていない場合には、 sys.__stdout__ に接続されているターミナルに os.get_terminal_size() を呼び出して問い合わせます。

システムが対応していない場合やターミナルに接続していないなどの理由でターミナルサイズの問い合わせに失敗した場合、 fallback 引数に与えられた値を利用します。 fallback のデフォルト値は (80, 24) で、これは多くのターミナルエミュレーターが利用しているデフォルトサイズです。

戻り値は os.terminal_size 型の名前付きタプルです。

参考: The Single UNIX Specification, Version 2, Other Environment Variables.

Added in version 3.3.

バージョン 3.11 で変更: os.get_terminal_size() がゼロを返した場合にも fallback の値を使うようになりました。

`shutil` --- 高水準のファイル操作¶

ディレクトリとファイルの操作¶

プラットフォーム依存の効率的なコピー操作¶

copytree の例¶

rmtree の例¶

アーカイブ化操作¶

アーカイブ化の例¶

base_dir を使ったアーカイブ化の例¶

出力ターミナルのサイズの取得¶

目次

前のトピックへ

次のトピックへ

このページ

shutil --- 高水準のファイル操作¶

ディレクトリとファイルの操作¶

プラットフォーム依存の効率的なコピー操作¶

copytree の例¶

rmtree の例¶

アーカイブ化操作¶

アーカイブ化の例¶

base_dir を使ったアーカイブ化の例¶

出力ターミナルのサイズの取得¶

`shutil` --- 高水準のファイル操作¶