uvで高速かつ再現性のあるPythonプロジェクトをセットアップする方法

Claude CodeやCodexのようなAIコーディングエージェントをPythonプロジェクトに向けたとき、摩擦の半分はモデルとは無関係だ。それは環境から生じる——パッケージの不足、間違ったPythonバージョン、エージェントが有効化し忘れたvirtualenv、あるいは「自分のマシンでは動く」というチームメイトだ。その解決策はデフォルトで再現可能なプロジェクトであり、今日それを手に入れる最速の方法が、AstralによるRustベースのPythonツールチェーンuvだ。

uvはpip、venv、pip-tools、pyenvを単一の高速なコマンドで置き換え、まったく同じ依存関係ツリーがどこでもインストールされるようにロックファイルを書き出す。このガイドでは、何もない状態から、ロックされた実行可能なプロジェクトまでを数分で構築する。

なぜ環境がエージェントにとって重要なのか

AIエージェントはあなたのシェルでコマンドを実行し、返ってくるエラーを読み取る。プロジェクトに宣言された依存関係も固定されたPythonバージョンもなければ、エージェントは推測するしかない——そして推測が間違えば、パッケージをグローバルにインストールしたり、間違ったインタプリタを編集したりといった泥沼に陥る。pyproject.tomlとuv.lockがあるプロジェクトは、エージェントに単一の信頼できる情報源を与える。エージェントはuv syncを実行し、正しいパッケージを取得して、先へ進める。あなたはレビューの時間を、環境の考古学発掘ではなくロジックに費やせるのだ。

uvをインストールする

macOSまたはLinuxの場合：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）の場合：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uvは単一の自己完結型バイナリなので、他に設定するものは何もない。

1つのコマンドでプロジェクトを開始する

uv init weather-cli
cd weather-cli

これで動作するプロジェクトの雛形ができる——メタデータと依存関係のためのpyproject.toml、.python-versionファイル、スターターとなるmain.py、README.md、そして.gitignoreだ。virtualenvを手作業で作成したり有効化したりする必要はない——必要になった瞬間に、uvが.venvを管理してくれる。

依存関係を追加する（そしてなぜロックファイルが重要なのか）

uv add requests

これは一度に3つのことを行う——requestsをpyproject.tomlに記録し、依存関係ツリー全体を解決し、正確でクロスプラットフォームに固定されたバージョンとともにuv.lockを書き出す。追加時にバージョンを固定することもできる：

uv add 'requests==2.31.0'

uv.lockをGitにコミットしよう。それは「最新のrequestsをインストールする」（時間とともにずれていく）と「テスト済みの正確なツリーをインストールする」との違いを生む。あなたのエージェント——あるいはCI、あるいは新しいチームメイト——がuv syncを実行すると、バイト単位で同一の環境を手に入れられる。

何も有効化せずにコードを実行する

uv run main.py

uv runは環境が同期されていることを確認し、その上で実行する——source .venv/bin/activateというお決まりの手順は不要だ。これは特にエージェントにとって重要だ。各ツール呼び出しはしばしば新しいシェルになるため、「有効化してから実行」は頻繁に壊れるが、単一のuv runは常に動作する。任意のコマンドをラップできる：

uv run -- pytest -q
uv run -- flask run -p 3000

エージェントとCIの足並みをそろえるためにPythonバージョンを固定する

uv python pin 3.12

これはバージョンを.python-versionに書き込み、uvはそのインタプリタを自動的にダウンロードして使用する——システムのPythonは必要ない。これで、あなたが開発に使うバージョンと、エージェント、チームメイト、CIが使うバージョンがすべて一致する。

短い実例

たとえば、エージェントに「今日の天気を取得するコマンドを追加して」と頼んだとしよう。uvがあれば、ループ全体がクリーンになる：

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# エージェントがAPIを呼び出すようにmain.pyを編集する...
uv run main.py

エージェントは、どのインタプリタが有効なのか、あるいはrequestsがインストールされているかどうかを推論する必要が一切ない——それらの事実は、エージェントが読み取れるファイルの中に宣言されている。新しい依存関係を導入する場合はuv addを実行し、ロックファイルが更新される。CIで何かが壊れた場合は、uv syncが正確な環境をローカルに再現するので、デバッグできる。

uvの今後

uvと、その兄弟ツールであるruff（リンター/フォーマッター）やty（型チェッカー）は広く採用されている——uvだけでも月間1億回をはるかに超えるダウンロードがある。2026年3月、OpenAIはAstral——これらを手がける企業——を買収することに合意し、ツールチェーンをCodexプラットフォームに統合する一方で、MITライセンスのツールをオープンソースのまま維持することを約束した（OpenAI、Simon Willison）。今のところ、実用的な要点は変わらない——uvは、AIエージェントが推測せずに構築できるPythonプロジェクトへの最速の道だ。

クイックリファレンス

タスク	コマンド
プロジェクトを作成する	uv init <name>
依存関係を追加する	uv add <package>
Pythonを固定する	uv python pin 3.12
コードを実行する	uv run <file or command>
環境を再現する	uv sync
ロックファイルを更新する	uv lock --upgrade-package <pkg>