Python uv コアコンセプト：pyproject.toml・ロックファイル・仮想環境

コマンドを闇雲に打つ前に、この 4 つのコンセプトを頭に入れてください：「依存関係はどこに書くか、ロックファイルは何のためにあるか、venv はいつ作られるか」が明確になります。ゲームをプレイする前にスキルの説明を読むようなもの — 読まないと意味もなく何度も死にます。

コンセプト 1：pyproject.toml はプロジェクトの身分証明書

プロジェクトのメタデータと依存関係はすべてここに書きます。PEP 518 の標準フォーマットです。

[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.31",
]

• 手動編集：pyproject.toml を直接編集
• コマンドで変更：uv add requests と uv remove requests が自動的に更新してくれる

混用しないこと — 手動かコマンドか、どちらかに統一。両方使うと衝突します。

コンセプト 2：uv.lock は依存関係のスナップショット

pyproject.toml は「何が欲しいか」を書きます（例：requests>=2.31）。uv.lock は「実際にインストールされたバージョン」を記録します — すべての推移的依存関係まで正確に。

• なぜロックファイルが必要か？ すべての人・すべての CI・本番環境が完全に同じ依存関係ツリーをインストールすることを保証します。「私の環境では動く、あなたの環境では壊れる」はもうなし。
• コミットすべきか？ はい。uv.lock はバージョン管理に入れて、チームと CI が同じ依存関係ツリーを使えるようにしてください。

# ロックファイルを更新（例：パッケージをアップグレード）
uv lock --upgrade-package requests

コンセプト 3：.venv はプロジェクト専用のサンドボックス

uv はプロジェクトルートに .venv を作成します — uv add したすべてのパッケージはここに入り、システム Python から隔離されます。

• 手動で activate する必要があるか？ いいえ。uv run が自動的にこの環境を使います。
• コミットすべきか？ いいえ。.venv は .gitignore に入れてください。

# 環境を手動同期（例：新しくクローンした後）
uv sync
source .venv/bin/activate  # その後 python、pytest などを直接使える

コンセプト 4：uv run は楽ちんな実行エントリーポイント

uv run は：

1. ロックファイルが pyproject.toml と整合しているか確認
2. .venv がロックファイルと同期していることを確認
3. 正しい環境で指定したコマンドを実行

uv run python main.py
uv run pytest
uv run flask run -p 3000

activate を覚える必要も、環境の間違いを心配する必要もない — uv に任せるだけ。トイレの場所を考えなくても自然に向かう猫のように。この「開けば動く」体験は、一度使ったら戻れません。

次のステップ

コアコンセプトを消化したら、高頻度の操作へ：依存関係管理・uvx・スクリプト実行。 👉 よくあるパターン