HOWTO · Python

Python のディレクトリとサブディレクトリにあるすべてのファイルを一覧表示する

このチュートリアルでは、Python でディレクトリとサブディレクトリ内のすべてのファイルを一覧表示する方法を示します。

このページの内容

開始ディレクトリ以下にあるすべてのファイルのパスを集めるには、Python の os.walk() を使います。これはディレクトリツリーをたどり、現在のディレクトリ、その子ディレクトリ名の一覧、現在のディレクトリにあるファイル名の一覧を順に返します。現在のディレクトリと各ファイル名を結合すると、ファイルのパスを作れます。ここで紹介する例は、ディレクトリ項目ではなくファイルを一覧表示します。

次の例を実行します。

このセクションのコードと表示されるラベルや出力は英語のままです。

from pathlib import Path
import os
import tempfile

with tempfile.TemporaryDirectory() as temporary_directory:
    root = Path(temporary_directory) / "project"
    (root / "reports").mkdir(parents=True)
    for relative_path in ("notes", "data.csv", "reports/summary.txt", "reports/2025.csv"):
        (root / relative_path).write_text("sample", encoding="utf-8")

    for current, directories, filenames in os.walk(root):
        directories.sort()
        for filename in sorted(filenames):
            print(Path(current, filename).relative_to(root))
data.csv
notes
reports/2025.csv
reports/summary.txt

この一時的な例は、拡張子のないファイルも含むディレクトリツリーを自分で作成し、開始ディレクトリからの相対パスを表示します。絶対パスを作るには、Path(current, filename) または os.path.join(current, filename) を使います。結果を保存するときは相対パスが便利です。ファイルをほかのコードに渡す場合は、絶対パスが役立ちます。パス区切り文字は、実行中のオペレーティングシステムに応じて選ばれます。

os.walk() でファイルを再帰的に一覧表示する

上のループでは、単純な再帰的一覧表示の基本として os.walk() を使っています。各反復で、1つ目の値は現在のディレクトリのパス、2つ目は子ディレクトリ名の変更可能なリスト、3つ目は現在のディレクトリにあるファイル名のリストです。ディレクトリを含めないようにするには、3つ目の値を使って反復します。走査順を一定にしたい場合は、子ディレクトリ名を並べ替えます。既定では走査エラーは無視されます。エラーをアプリケーションで報告する必要があれば、onerror を指定してください。

os.listdir() で独自の再帰走査を実装する

os.listdir(path) は1つのディレクトリにある項目名を返します。子ディレクトリまではたどりません。独自に走査するには、調べるパスをスタックで管理します。各パスについて os.listdir(path) の結果を反復し、各名前を os.path.join() で親ディレクトリと結合します。ファイルは結果に追加し、ディレクトリはスタックに追加します。項目の種類は os.path.isfile() と os.path.isdir() で確認します。この方法では走査順やフィルタリングを自由に制御できますが、再帰処理とファイルシステムのエラー処理は自分で実装する必要があります。

os.scandir() でディレクトリ項目を調べる

os.scandir(path) は、1つのディレクトリにある項目を DirEntry オブジェクトとして返します。is_file() と is_dir() メソッドを使うと、どの項目を集めるか、子ディレクトリをたどるかを簡単に判断できます。前述のスタックを使う走査にこの方法を適用し、各ディレクトリを with os.scandir(path) as entries: で開くと、反復処理が確実に終了したときにイテレーターが閉じられます。項目の種類やメタデータに応じて処理を決める場合に便利です。

glob.glob() でパターンに一致するファイルを探す

パターンで項目を選ぶには、glob.glob(os.path.join(root, "**", "*"), recursive=True) を使うと、拡張子のない名前も含め、任意の深さにある名前を照合できます。recursive=True を有効にすると、パターンの ** がディレクトリ階層にまたがって照合されます。glob の結果にはディレクトリも含まれることがあるため、ファイルだけが必要なら os.path.isfile(path) で絞り込みます。特定の種類のファイルを選ぶには、"**/*.csv" のような、より限定したパターンを使います。"*.*" では、名前にドットがない項目は対象になりません。

pathlib.Path でファイルを再帰的に一覧表示する

pathlib.Path(root).rglob("*") は、ルート以下のパスを再帰的に返します。ディレクトリを除くには、結果を path.is_file() で絞り込みます。返されるのは Path インスタンスなので、文字列を手作業で結合しなくても relative_to(root) や name などのメソッドを使えます。API が文字列のパスを必要とする場合は、str(path) を使います。

用途に応じて方法を選ぶ

ファイル名と子ディレクトリ名が分かれている、わかりやすい既定の方法には os.walk() を選びます。走査中に項目の種類やメタデータを調べるなら os.scandir() が適しています。パターンで照合する場合は glob.glob() を、パスオブジェクトを使うコードでは pathlib.Path.rglob() を使います。独自の走査方法が必要で、その実装を用意できる場合は os.listdir() を選びます。これらの方法が返すのはパスまたは名前であり、ファイルの内容ではありません。ファイルを読み取ったり処理したりするには、パスを別途開きます。開始ディレクトリが存在しない場合や読み取れない場合は、使用するAPIとアプリケーションに必要な動作に応じてファイルシステムのエラーを処理してください。