pyproject.toml

定義

pyproject.toml は Python プロジェクトのルートに置く TOML 形式の設定ファイルである。
パッケージのビルドに使うバックエンド、名前・バージョン・依存関係といったメタデータ、テストやフォーマッタなど各ツールの設定を 1 つのファイルにまとめる。setup.py や setup.cfg に分散していた情報の置き場所として標準化された。

詳細

中身は 3 つのテーブルに分かれる。

• [build-system]: ビルドバックエンドと、ビルドに必要な依存を書く。
  PEP 518 で定義された
• [project]: 名前・バージョン・dependencies などのメタデータを書く。
  PEP 621 で定義された
• [tool]: [tool.pytest.ini_options] や [tool.uv] のように、ツールごとの設定を下位テーブルに書く

pip install . は [build-system] に書かれたバックエンドを隔離環境に入れてからビルドするので、ここが誤っているとビルド段階で失敗する。uv の uv sync や uv add はこのファイルを探してプロジェクトの範囲を決めるため、見つからない場所で実行すると 「No pyproject.toml found」で止まる。

よくある誤解

• パッケージを配布するときだけ要る: 配布しないアプリでも、uv のプロジェクト管理や pytest の設定置き場として使われる。
• setup.py は必ず併用する: 新規プロジェクトでは [project] テーブルで足りる。setup.py が要るのは C 拡張のビルドのように設定を手続きで書く必要がある場合である。
• requirements.txt と同じもの: requirements.txt はインストールする版を並べたリストで、プロジェクト自身の定義は持たない。

関連

依存をインストールする先は venv で作る仮想環境である。
仕様の経緯は PEP の番号で追える。