【2026年版】AI開発環境はuvで整える
Claude・Codex時代のPython環境構築ガイド
Claude、Codex、Gemini CLI などのAI開発ワークフローでは、再現性のあるPython環境が重要です。uvでpip・venv・pyenv・Poetryを一本化し、AIコーディング時代の環境構築を解説します。
Claude、Codex、Gemini CLI などのAI開発ツールを使うとき、地味に効いてくるのが Python環境の再現性 です。AIにコードを書かせても、ローカル環境やCIで依存関係がずれていると、動作確認や修正のたびに時間を失います。
「pip と venv をセットで使い、pyenv でバージョンを管理して、さらに Poetry で依存関係を整理して…」Python の開発環境は、長年にわたって複数のツールを組み合わせるのが当たり前でした。それが 2024 年以降、uv の登場で一気に変わりつつあります。
本記事では、AIコーディング時代のPython開発環境として uv をどう使うかを、pip/venv 以上のことはよく知らないエンジニアにも分かるように解説します。読み終えた後には、uv ひとつで再現性のあるPython環境を整え、AIに任せたコード変更も確認しやすくなります。
uv とは？ なぜ注目されているのか
uv は、Astral（Python リンター「Ruff」を開発した会社）が作った Rust 製の Python パッケージマネージャーです。2024 年にリリースされ、2026 年現在では個人プロジェクトから企業の本番環境まで広く採用が進んでいます。
これまでの Python 開発環境の問題点
Python の開発環境構築は、長年こんな複数ステップが当たり前でした。
| やりたいこと | 従来のツール |
|---|---|
| パッケージのインストール | pip |
| 仮想環境の作成 | venv / virtualenv |
| Python バージョンの切り替え | pyenv |
| プロジェクトの依存関係管理 | Poetry / Pipenv |
これを別々に覚えて、別々にインストールして、組み合わせる必要がありました。初心者にとっては「何から始めればいいの？」となりがちです。
uv はこれを全部まとめてしまう
uv は上記 4 つをすべて 1 つのツールで代替できます。
| やりたいこと | uv のコマンド |
|---|---|
| パッケージのインストール | uv add |
| 仮想環境の管理 | 自動（.venv に作成） |
| Python バージョン管理 | uv python install |
| 依存関係管理（ロックファイル） | uv.lock（自動生成） |
しかも Rust 製なので、pip と比べてキャッシュなしで 8〜10 倍、キャッシュありで 80〜115 倍の速度でパッケージをインストールできます（公式ベンチマーク）。
uv のインストール方法
公式が提供するインストーラーが最もシンプルで確実な方法です。
macOS / Linux
ターミナルで以下を実行します。
curl -LsSf https://astral.sh/uv/install.sh | shインストール後、シェルを再起動（または source ~/.bashrc / source ~/.zshrc）すれば uv コマンドが使えるようになります。
Windows
PowerShell で以下を実行します。
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"winget でも対応しています。
winget install --id=astral-sh.uv -eインストール確認
uv --version
# uv 0.x.x (...)バージョンが表示されれば成功です。
プロジェクトを始める: uv init
新しい Python プロジェクトを作るときは uv init を使います。
uv init my-project
cd my-project実行後のファイル構成はこちらです。
my-project/
├── .python-version # 使用する Python バージョン
├── pyproject.toml # プロジェクト設定・依存関係
├── README.md
└── hello.py # サンプルスクリプトpyproject.toml は npm の package.json に相当するファイルで、プロジェクトのメタ情報や依存パッケージを記録します。uv が自動で管理してくれるので、手動編集はほぼ不要です。
特定の Python バージョンを指定したい場合はオプションで渡します。
uv init my-project --python 3.12よくあるつまずきポイント
uv init を実行するディレクトリはプロジェクトのルートにしてください。ネストしてしまうと pyproject.toml が二重になることがあります。
パッケージの追加・削除: uv add / uv remove
パッケージを追加するには uv add を使います。
# パッケージを追加
uv add requests
# 複数まとめて追加
uv add fastapi uvicorn
# 開発時のみ使うパッケージ（テストツールなど）
uv add --dev pytest ruffuv add を実行すると、次のことが自動で行われます。
.venv/に仮想環境が作成される（初回のみ）pyproject.tomlの[dependencies]にパッケージが追記されるuv.lockにバージョンが確定・記録される- パッケージがインストールされる
削除は uv remove です。
uv remove requestspip のようにグローバルにインストールする必要はありません。uv はプロジェクトごとに仮想環境を分離して管理するので、別プロジェクトの依存関係と混在しません。
スクリプトを実行する: uv run
仮想環境をアクティベートせずにそのままスクリプトを実行できます。
uv run hello.pysource .venv/bin/activate のようなアクティベーション手順が不要になるのは、地味ですが毎日使うと効いてきます。
pytest などの開発ツールも同様に実行できます。
uv run pytest
uv run ruff check .Python バージョンを管理する: uv python
pyenv の役割も uv が担います。
Python のインストール
# 最新の Python 3.12 をインストール
uv python install 3.12
# 複数バージョンをインストール
uv python install 3.11 3.12 3.13インストール済みのバージョン一覧を確認するには次のコマンドです。
uv python listプロジェクトの Python バージョンを固定する
uv python pin 3.12このコマンドで .python-version ファイルに 3.12 が記録されます。チームメンバーが uv sync を実行すると、同じバージョンが自動的に使われるようになります。
チーム開発での環境再現: uv sync と uv.lock
チーム全員が同じ依存関係で作業できるのが uv の大きな強みです。
uv.lock の役割
uv add を実行すると uv.lock が自動生成されます。このファイルには全依存パッケージの確定バージョンが記録されており、npm の package-lock.json に相当します。
uv.lock は Git にコミットしてください。 これにより、チームメンバー全員・CI 環境・本番環境で同じバージョンが保証されます。
環境の再現
リポジトリをクローンして環境を作るときは uv sync 一発です。
git clone <repo>
cd <repo>
uv syncpyenv + pip + venv の複数ステップが、このコマンドひとつに集約されます。
AI開発ワークフローでuvが効く理由
AIコーディングでは、ClaudeやCodexに「このライブラリを使って実装して」「テストを追加して」と依頼する場面が増えます。このとき、依存関係が pyproject.toml と uv.lock にまとまっていると、AIが変更すべき場所を判断しやすくなります。
特に便利なのは次の3点です。
- 環境再現が速い:
uv syncだけで、AIが前提にした依存関係を再現できる - 実行コマンドが明確:
uv run pytestやuv run ruff check .のように、AIにも人間にも伝えやすい - グローバル環境を汚さない: AIが提案したパッケージを試すときも、プロジェクト単位で閉じられる
Claude Code、Codex、Gemini CLI のようなエージェントに作業させる場合も、「変更後は uv run pytest を実行する」「新しい依存関係は uv add で追加する」とルール化しておくと、環境差分による失敗を減らせます。
トラブルシューティング
| 症状 | 対処 |
|---|---|
uv: command not found | シェルの再起動、または ~/.local/bin を PATH に追加 |
uv run してもパッケージが見つからない | uv sync を実行して仮想環境を更新 |
| Python バージョンが意図と違う | .python-version を確認し uv python pin で指定 |
| CI で uv が使えない | pip install uv または公式インストーラーを CI に追加 |
よくある質問（FAQ）
Q. pip は完全に捨てていいの？
A. ほとんどのケースで pip は不要になります。ただし、uv を使わないプロジェクトとの共存や、システムレベルのインストールが必要な場面ではまだ pip が役立つこともあります。新規プロジェクトなら最初から uv を選ぶのがおすすめです。
Q. Poetry や Pipenv から乗り換えるのは大変？
A. pyproject.toml の書式は共通なので移行は比較的スムーズです。uv add で依存パッケージを追加し直せば uv.lock が生成されます。詳細は公式のプロジェクトガイドを参照してください。
Q. VSCode で仮想環境を認識させるには？
A. コマンドパレット（Ctrl+Shift+P）から「Python: Select Interpreter」を選択し、.venv/bin/python（Windows は .venv\Scripts\python.exe）を指定してください。uv が自動生成した .venv が表示されるはずです。
Q. ruff や black などのグローバルツールはどう管理する？
A. uv tool install ruff でグローバルにインストールできます。これは pipx の代替として機能するので、ツール用に別途 pipx を入れる必要もなくなります。
Q. uv 自体のアップデートは？
A. uv self update コマンドで最新版に更新できます。
まとめ
uv を使うことで、これまで 4 つのツール（pip・venv・pyenv・Poetry）で管理していた Python 開発環境を、1 つのコマンドに集約できます。Rust 製の圧倒的な速度と、シンプルなコマンド体系が特徴です。
AIにコードを書かせる時代ほど、「誰が実行しても同じ環境になる」ことが重要です。uv で依存関係とPythonバージョンを固定しておけば、Claude、Codex、Gemini CLI に任せた変更も検証しやすくなります。
まずは以下の 3 ステップから試してみてください。
uvをインストール（ワンライナー）uv init my-projectでプロジェクト作成uv add requestsでパッケージ追加 →uv run hello.pyで実行
関連記事
- AI開発 — AI時代の開発環境、CLI、エージェント、自動化
- ClaudeのProjects × Memory 完全設定ガイド — 文脈が続くAI業務アシスタントの作り方
- AI開発環境でBunとNode.jsをどう選ぶか — ランタイム選定の実務チェックリスト
- Cursor 3.0 Agents Window 入門：マルチエージェント並列実行の使い方 — AIコーディング環境のエージェント活用
慣れてきたら uv python によるバージョン管理や uv.lock を活用したチーム開発に進んでみましょう。