こんにちは！日々の開発、本当にお疲れ様です。
Pythonのプロジェクトを作るとき、`setup.py`を書いたり、とりあえず`requirements.txt`にライブラリを羅列したりしていませんか？
実は、Pythonのパッケージ管理の世界はここ数年で劇的な進化を遂げました。かつての「お決まりの儀式」だった設定ファイルたちは次々と役目を終え、現在は『pyproject.toml』というたった一つのファイルに統合されつつあります。
今回は、未来のPython開発のスタンダードである「PEP 621」を軸に、レガシーな依存関係管理から完全に脱却する方法を、優しく、そして徹底的に解説していきます。
これをマスターすれば、`pip`、`Poetry`、そして今最も熱い超高速ツール`uv`のどれに乗り換えても、設定に迷うことがなくなります。毎日のコーディング環境の構築が、劇的にスムーズになりますよ！
—
なぜ今、`pyproject.toml`（PEP 621）なのか？
これまでのPython界隈は、ツールごとに設定ファイルがバラバラでした。
- ライブラリのメタデータ定義：`setup.py` や `setup.cfg`
- 依存関係の固定：`requirements.txt`
- リンターやフォーマッター（Black, Flake8など）の設定：`tox.ini` や各種設定
「ツールが変わるたびに設定ファイルの書き方を覚える必要がある」「`setup.py`の中身がブラックボックス化して動かせない」……そんな地獄のような状態を解決するために策定されたのが、PEP 621 です。
PEP 621は、「プロジェクトのメタデータ（名前、依存関係など）の書き方を標準化しようぜ」というPythonの公式提案（PEP）です。これにより、ビルドバックエンドやパッケージマネージャーが違っても、`pyproject.toml` さえ見ればプロジェクトの全容がひと目でわかるようになりました。
—
基礎セットアップ：現代のPythonプロジェクトの正しい構造
まずは、ツール（pip, Poetry, uv）の垣根を超えて共通で使える、美しいプロジェクトのディレクトリ構成を見てみましょう。
my_awesome_project/
├── .venv/ # 仮想環境（ツールが自動生成）
├── pyproject.toml # ★今回主役の標準設定ファイル
├── README.md # プロジェクトの概要
├── src/ # ソースコード格納ディレクトリ（srcレイアウト）
│ └── my_package/
│ ├── __init__.py
│ └── main.py
└── tests/ # テストコード
└── test_main.py
この「`src`レイアウト」を採用するのが、現代のPython開発におけるベストプラクティスです。意図しないローカルパッケージのインポートエラーを防ぎ、クリーンなテスト実行が可能になります。
—
実践：PEP 621完全準拠の `pyproject.toml` を書く
それでは、将来どのツール（pip, Poetry, uv）に移行しても通用する、最も美しく拡張性の高い `pyproject.toml` を書いてみましょう。
[build-system]
パッケージをビルドするためのバックエンドを指定します（通常はhatchlingやsetuptools）
requires = [“hatchling”]
build-backend = “hatchling.build”
[project]
PEP 621準拠のプロジェクトメタデータ定義
name = “my_awesome_project”
version = “0.1.0”
description = “未来のPython開発に向けたPEP 621準拠のサンプルプロジェクト”
readme = “README.md”
requires-python = “>=3.10”
license = { text = “MIT” }
authors = [
{ name = “あなたの名前”, email = “your.email@example.com” }
]
このプロジェクトが依存する外部ライブラリ（最小限の記述）
dependencies = [
“requests>=2.31.0”,
“pydantic>=2.0.0”,
]
開発時にのみ使用する依存関係（テストや型チェックなど）
[project.optional-dependencies]
dev = [
“pytest>=7.0.0”,
“black>=23.0.0”,
]
[tool.hatch.build.targets.wheel]
srcレイアウトを採用していることをビルドシステムに教えます
packages = [“src/my_package”]
このファイルの美しいところは、「どのパッケージマネージャーを使うか」に依存しない、ピュアなPython標準の記述である点です。
—
各ツール（pip / Poetry / uv）でのスマートな運用方法
では、この `pyproject.toml` を使って、実際の開発フローをそれぞれのツールでどう回すのかを見ていきましょう。
1. 超高速次世代ツール `uv` を使う場合（現在最もおすすめ！）
Rust製で驚異的な速さを誇る `uv` は、PEP 621の `pyproject.toml` をネイティブで完璧にサポートしています。
1. 仮想環境を作成して有効化
uv venv
source .venv/bin/activate # Windowsなら .venv\Scripts\activate
2. 依存関係をインストール（pyproject.tomlを自動検知）
uv pip install -e .[dev]
3. 依存関係のロックファイルを生成（再現性の担保）
uv pip compile pyproject.toml -o requirements.txt
`uv` は従来の `pip` と完全に互換性を持ちながら、数十倍の速度で動作します。毎日のインストール待ち時間から完全に解放されますよ。
2. 王道パッケージマネージャー `Poetry` を使う場合
Poetryは独自の依存関係解決エンジンのため、`pyproject.toml` 内に Poetry 専用の設定セクション（`[tool.poetry]`）を追加することで、PEP 621と共存させることができます。
Poetryを使う場合、プロジェクトセクションはPoetryの規格に一部準拠します
[tool.poetry]
name = “my_awesome_project”
version = “0.1.0”
description = “”
authors = [“Your Name
readme = “README.md”
packages = [{ include = “my_package”, from = “src” }]
[tool.poetry.dependencies]
python = “>=3.10”
requests = “^2.31.0”
pydantic = “^2.0.0”
[tool.poetry.group.dev.dependencies]
pytest = “^7.0.0”
Poetryは、仮想環境の自動管理やパッケージの公開（PyPIへのアップロード）までワンストップで行いたい場合に非常に強力です。
3. レガシーな `pip` + `setuptools` を使う場合
もし社内の制約などで従来の `pip` を使わざるを得ない場合でも、`pyproject.toml` さえあれば `setup.py` はもう不要です。
仮想環境を作成
python -m venv .venv
source .venv/bin/activate
編集可能モード（Editable mode）でインストール
pip install –upgrade pip
pip install -e .[dev]
これだけで、`pyproject.toml` の `[project]` セクションを読み取り、安全に環境を構築してくれます。
—
精度高い Hello World 的な動作確認
正しく環境が構築できているか、実際にコードを書いて確認してみましょう。先ほどのディレクトリ構成に沿ってファイルを作成します。
`src/my_package/main.py`
from pydantic import BaseModel
import requests
Pydanticを使ったデータモデルの定義
class User(BaseModel):
name: str
id: int
def get_sys_info() -> str:
# 外部ライブラリ（requests）の簡単な動作確認
response = requests.get(“https://httpbin.org/json”, timeout=5)
return f”API Status: {response.status_code}”
def main():
user = User(name=”DevOps Architect”, id=42)
print(f”User created: {user.name} (ID: {user.id})”)
print(get_sys_info())
if __name__ == “__main__”:
main()
実行と動作確認
ターミナルで以下のコマンドを実行してください。
python -m src.my_package.main
実行結果（ログ例）:
User created: DevOps Architect (ID: 42)
API Status: 200
おめでとうございます！`requests` と `pydantic` という実用的な外部ライブラリが、PEP 621準拠の `pyproject.toml` を通じて美しく管理され、エラーなく実行されました。
—
先輩エンジニアからの実践アドバイス
最後に、実務でこの構成を運用する上での重要な知見を一つ。
将来的にチームメンバーや使うツールが変わったとしても、「設定の記述は `pyproject.toml` に集約する」という原則さえ守っておけば、`pip` から `uv` へ、あるいはその逆への移行も数分で完了します。もはやバラバラの `setup.py` や手動の `requirements.txt` に怯える必要はありません。
標準規格である PEP 621 をマスターして、快適でモダンなPythonライフを存分に楽しんでください！