Claude Code × uv で Python 環境を瞬速構築する

Pythonプロジェクトを始めるたびに、こんな状況に陥ったことはないでしょうか。

pyenv install 3.12.0      # 数分待つ
pyenv virtualenv 3.12.0 myproject
pyenv activate myproject
pip install -r requirements.txt  # さらに数分待つ

pyenv・virtualenv・pip の三重管理に疲れた方に試してほしいのが uv です。Rust製のパッケージマネージャーで、インストール速度はpipの10〜100倍。Claude Codeと組み合わせると、環境構築にかかっていた時間がびっくりするほど短縮されます。私自身、複数のPythonプロジェクトをuvに移行してから「なぜもっと早く使わなかったんだろう」と思いました。

uv とは何か

uvはAstral社が開発したRust製のPythonパッケージ・プロジェクト管理ツールです。pip install numpy が30秒かかる環境でも、uv add numpy なら2〜3秒で完了することも珍しくありません。

主な特徴をまとめると:

pipの完全互換コマンド: pip install → uv pip install に置き換えるだけで使い始められます
仮想環境管理も一体化: pyenv + virtualenv の代わりになり、管理ツールが1つに絞れます
Pythonバージョン管理まで: uv python install 3.12 でPython本体も管理できます
pyproject.toml 対応: 現代的なプロジェクト管理形式に標準対応しています

2026年時点で、個人開発・OSSコミュニティ双方でuvの採用が急速に広まっています。Anthropic自身のPython SDKも、開発環境ガイドでuvを推奨しています。

Claude Code との組み合わせが効く理由

Claude Codeを使ってPythonプロジェクトを作るとき、依存関係の管理でよくつまずくのは「どのパッケージが必要か」「バージョン指定はどうするか」という判断です。uv + Claude Code のコンビだと、Claudeがコードを見ながら必要なパッケージを即座に提案・追加してくれます。

たとえば、こんな指示一つで:

FastAPI + SQLAlchemy + AlembicでユーザーAPIを作って。
uvで環境管理して、開発・本番で依存関係を分けて

Claude Codeは以下を自動で実行します:

# プロジェクト初期化（仮想環境も自動作成）
uv init myapi
cd myapi
 
# 本番依存関係
uv add fastapi uvicorn sqlalchemy alembic python-jose passlib
 
# 開発専用依存関係
uv add --dev pytest httpx ruff mypy

この一連のコマンドをClaude Codeが生成・実行し、pyproject.toml も自動で更新されます。pipを直接使うより明らかに速く、エラーも少ないです。

実際のプロジェクトセットアップ手順

Step 1: uv のインストール

まずuv自体を入れます。インストールは30秒もかかりません:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Windows の場合
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 
# インストール確認
uv --version
# uv 0.5.x

Step 2: Claude Code に新規プロジェクトを作らせる

Claude Codeのターミナルで指示します:

uvを使ってPython 3.12のプロジェクトを作って。
FastAPIのAPIサーバーをベースに、
- ヘルスチェックエンドポイント
- 環境変数の読み込み（python-dotenv）
- ロギング設定
を含むスケルトンをセットアップして

Claude Codeが生成するプロジェクト構成の例:

myapi/
├── pyproject.toml      # 依存関係 + プロジェクト設定
├── .python-version     # 3.12（uv が自動読み取り）
├── .venv/              # 仮想環境（uv init で自動生成）
├── src/
│   └── myapi/
│       ├── __init__.py
│       ├── main.py
│       └── config.py
└── tests/
    └── test_main.py

生成される pyproject.toml の例:

[project]
name = "myapi"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115",
    "uvicorn[standard]>=0.32",
    "python-dotenv>=1.0",
]
 
[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "httpx>=0.27",
    "ruff>=0.8",
]
 
[tool.ruff.lint]
select = ["E", "F", "I"]

Step 3: 開発中の依存関係追加もClaude Codeに任せる

開発中に新しいライブラリが必要になったとき:

SQLAlchemyでPostgresに非同期接続したい。
uvで必要なパッケージを追加して、接続設定のコードも書いて

Claude Codeが実行するのは:

uv add sqlalchemy[asyncio] asyncpg alembic
 
# pyproject.toml が自動更新される
# .venv に秒速でパッケージが追加される

手動で requirements.txt を管理していた頃と比べると、この流れがとにかく楽です。Claude Codeが「このコードにはこのパッケージが必要」と判断して、依存関係を自動で追加してくれることもあります。

よくある詰まりポイントと Claude Code の対処

詰まりポイント1: uv: command not found（パス未設定）

uvをインストールしてもシェルが認識しないことがあります。Claude Codeに「uvがcommand not foundになる」と伝えると、~/.cargo/bin や ~/.local/bin へのPATH追加コマンドを即座に提案してくれます。新しいターミナルセッションを開くか、source ~/.bashrc を実行するよう案内してくれることも多いです。

詰まりポイント2: 既存の requirements.txt からの移行

既存プロジェクトをuvに移行したいときは:

requirements.txtがあるPythonプロジェクトをuvに移行して。
pyproject.tomlに変換して、開発用と本番用の依存関係を分けて

Claude Codeが requirements.txt を読み込み、uv pip compile を使った変換を自動で行います。依存関係に矛盾がある場合も、Claude Codeが適切なバージョン解決を提案してくれます。

詰まりポイント3: GitHub Actions でのuv活用

CI/CDにも対応できます。Claude Codeに「GitHub ActionsでuvをCI環境で使いたい」と伝えると:

# Claude Code が生成するワークフロー例
- name: Set up uv
  uses: astral-sh/setup-uv@v4
 
- name: Install dependencies
  run: uv sync --frozen  # uv.lock で完全に再現可能なインストール
 
- name: Run tests
  run: uv run pytest

uv.lock ファイルをリポジトリにコミットしておけば、CIでも開発環境とまったく同じ依存関係を再現できます。これがpip + requirements.txt との大きな違いの一つです。

pip からの移行は思ったより簡単

「途中から移行するのは怖い」と感じるかもしれませんが、uvはpipの完全な上位互換として設計されています:

# 既存の仮想環境を活かしたまま pip を uv に置き換える
uv pip install -r requirements.txt  # これだけで移行完了
 
# 次のプロジェクトからは uv ネイティブで始める
uv init next-project

Claude Codeは既存プロジェクトの構成を分析して、段階的な移行計画まで提案してくれます。「本番環境は触りたくないが開発環境だけ移行したい」という場合の対処も得意です。

FastAPIを使ったAPI開発に進みたい方は、Claude Code × FastAPI 本番APIガイドもあわせてご覧ください。テスト・デプロイまで含めた全体像はClaude Code Python 開発完全ガイドが参考になります。

uvのような新ツールが登場しても、Python言語そのものの理解が土台になります。

次のステップ

まず既存のPythonプロジェクトで uv pip install -r requirements.txt を一度試してみてください。pipより大幅に速い体験ができるはずです。速さを実感したら、次のプロジェクトは uv init から始めて、Claude Codeに依存関係管理を任せるところまで進めてみてください。Pythonプロジェクトのセットアップに費やす時間が、想像より大きく変わります。

Claude Code × uv で Python 環境を瞬速構築する — pip より 10 倍速いパッケージ管理の現場活用