pyproject.toml は、Python プロジェクトの設定を1か所にまとめるための標準ファイルです。 依存関係、パッケージのメタ情報、各種ツールの設定を、TOML 形式で記述します。
何がまとまったのか
かつては役割ごとにファイルが分かれていました。
| 昔 | 今 |
|---|---|
setup.py / setup.cfg |
pyproject.toml の [project] |
requirements.txt |
[project] の dependencies |
.flake8 / pytest.ini など |
[tool.<ツール名>] |
ツールごとの設定が [tool.black] [tool.ruff] のように名前空間で分かれているのがポイントです。ツールが増えても衝突しません。
依存はここ、固定はロックファイル
役割を混同しないでください。pyproject.toml に書くのは自分が直接使うライブラリと、許容するバージョンの範囲です。
dependencies = ["requests>=2.31", "fastapi>=0.110"]
実際に入った版の組み合わせを記録するのはロックファイルの役目です。pip の requirements.txt を pip freeze で作っていた頃と違い、直接依存と間接依存が混ざりません。
なお 2025年3月に PEP 751 が Final となり pylock.toml が共通のロックファイル形式として標準化されています。設定は pyproject.toml、固定は pylock.toml、という分担が今後の標準形です。
TOML なので YAML の罠が無い
YAML と違い、TOML はインデントに意味がなく、型の推測もしません。文字列は必ず引用符で囲むため、1.10 が 1.1 になったり no が偽になったりしません。設定ファイル形式としては素直で、事故が起きにくい選択です。