uvでAI開発環境を構築する — Claude SDKプロジェクトを0.87秒で始める方法

uvでAI開発環境を構築する — Claude SDKプロジェクトを0.87秒で始める方法

RustベースのPythonパッケージマネージャーuv 0.11でanthropicやopenaiなどのAI SDK開発環境を設定する完全実践ガイド。pip比100倍以上の高速インストール、再現性の高い環境管理、Claude SDKプロジェクトの初期化まで実ログで丁寧に解説します。

去年まで、AIプロジェクトを始めるたびに同じ手順を繰り返していた。python -m venv .venv、source .venv/bin/activate、pip install anthropic openai……そして待った。長いときは2分以上。anthropic、torch、pydanticといったパッケージが順番にダウンロードされるのをただ眺めながら。

コンテキストスイッチのコストは意外と大きい。新しい実験ブランチを作るたびに、環境セットアップがフローを断ち切った。「自分のPCでは動いたのに」問題も消えなかった。

そんなときuvを使い始めた。Rustで作られたPythonパッケージマネージャーで、Ruffを開発したAstralチームの作品だ。今日Claude SDKプロジェクトをセットアップしながら実際に計測してみたところ — anthropicを含む16パッケージのインストールに0.874秒かかった。pipなら20〜40秒はかかっていた作業だ。

この記事はuv 0.11をベースに、AI開発環境をゼロから構築する完全実践ガイドだ。

なぜ今uvなのか — pip、Poetry、condaの何が問題か

正直なところ、pip自体が問題なわけではない。何十億ものパッケージをダウンロードしてきた実績ある道具だ。問題は速度と環境の分離の組み合わせにある。

AI開発環境でpipが遅い理由は構造的だ。パッケージを逐次的に解決し、ダウンロード済みファイルを効率的にキャッシュできない。pip install anthropic openai torchを実行すると、各パッケージのメタデータ取得、依存関係の解決、競合確認がシリアルに走る。

Poetryは依存関係管理の面でずっと優れている。pyproject.tomlベースの宣言的設定、ロックファイルのサポート。ただしPoetry自体がPythonで書かれているため速度に限界があり、環境が壊れたときのデバッグがかなり面倒になる。

condaはPythonバージョン管理に強みがあるが、環境自体が数ギガバイトに膨れあがりがちで、Docker CIで使いづらい。

uvはRustで書かれているため、並列ダウンロードとキャッシュ活用で根本的に異なる性能を発揮する。今日実際に計測した結果:

uv init claude-agent-demo    →  0.435秒
uv add anthropic             →  0.874秒（16パッケージ、pydantic-core 1.9MB含む）
uv sync（キャッシュヒット時）   →  0.074秒（19パッケージを29msでインストール）

Prerequisites — インストール前の確認

uvのインストールに必要なものはほぼない。OSごとに以下を確認するだけだ。

  • macOS/Linux: curlまたはHomebrew
  • Windows: PowerShell
  • Pythonを事前にインストールしなくてよい。uvが直接管理できる

Pythonバージョンの要件がないという点が大きなメリットだ。uvはPythonインタープリター自体をダウンロードして管理できるため、システムのPythonバージョンを気にする必要がない。

Step 1: uvのインストール

macOSとLinuxは公式インストールスクリプト一行で完了する。

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

Homebrewを使うなら:

brew install uv

Windows PowerShell:

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

インストール後のバージョン確認:

uv --version
# uv 0.11.11 (ed7b06001 2026-05-06)

現時点での最新は0.11.11だ。2026-05-06ビルド。Astralのリリースサイクルは速く、uv self updateでいつでも最新版に更新できる。

Step 2: AIプロジェクトの初期化

uv initで新しいプロジェクトを作る。

uv init claude-agent-demo
cd claude-agent-demo

実行結果:

Initialized project `claude-agent-demo` at `/path/to/claude-agent-demo`

0.435秒で完了する。生成されるファイル構造:

claude-agent-demo/
├── main.py
├── pyproject.toml
└── README.md

pyproject.tomlがデフォルトで生成される:

[project]
name = "claude-agent-demo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

.envファイルもこのタイミングで設定しておくとよい:

cat > .env << 'EOF'
ANTHROPIC_API_KEY=your-api-key-here
EOF

Step 3: Claude SDKの追加

uv add anthropic

実際の実行ログ:

Using CPython 3.11.12
Creating virtual environment at: .venv
Resolved 17 packages in 514ms
Downloading pydantic-core (1.9MiB)
 Downloaded pydantic-core
Prepared 16 packages in 269ms
Installed 16 packages in 20ms
 + annotated-types==0.7.0
 + anthropic==0.100.0
 + anyio==4.13.0
 + certifi==2026.4.22
 + distro==1.9.0
 + docstring-parser==0.18.0
 + h11==0.16.0
 + httpcore==1.0.9
 + httpx==0.28.1
 + idna==3.13
 + jiter==0.14.0
 + pydantic==2.13.4
 + pydantic-core==2.46.4
 + sniffio==1.3.1
 + typing-extensions==4.15.0
 + typing-inspection==0.4.2

pydantic-coreが1.9MBあるにもかかわらず、全体のインストールが0.874秒で完了した。キャッシュなしの初回インストール基準だ。

複数のSDKをまとめて追加する場合も同様に速い:

uv add openai httpx python-dotenv
Resolved 21 packages in 232ms
Installed 3 packages in 19ms
 + openai==2.35.1
 + python-dotenv==1.2.2
 + tqdm==4.67.3

0.555秒。anthropicとopenaiが同じhttpxを依存関係として共有しているが、uvは重複なく必要なものだけを追加した。この依存関係の衝突管理はpipでしばしば予期しないバージョン変更を引き起こすポイントだ。

Step 4: 最初のClaudeスクリプトを実行する

main.pyを作成する:

import anthropic
import os
from dotenv import load_dotenv

load_dotenv()

def main():
    client = anthropic.Anthropic(
        api_key=os.environ.get("ANTHROPIC_API_KEY")
    )
    
    message = client.messages.create(
        model="claude-opus-4-7-20260401",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": "uvがpipより速い理由を一言で説明してください。"}
        ]
    )
    
    print(message.content[0].text)

if __name__ == "__main__":
    main()

実行:

uv run main.py

uv runの最大のメリットはvirtualenvを直接アクティベートしなくてよい点だ。source .venv/bin/activateなしでもプロジェクト環境でスクリプトが実行される。

Vercel AI SDKを使ったClaudeストリーミングエージェント実装も同じアプローチで始められる。PythonプロジェクトならuVの方がはるかに速い。

Step 5: Pythonバージョン管理

uvの隠れた強みのひとつがPythonバージョン管理だ。pyenvなしにuvだけで複数のPythonバージョンをインストールして切り替えられる。

インストール可能なバージョン一覧:

uv python list

出力の一部:

cpython-3.15.0a8-macos-aarch64-none      <download available>
cpython-3.14.5rc1-macos-aarch64-none     <download available>
cpython-3.13.13-macos-aarch64-none       <download available>
cpython-3.13.11-macos-aarch64-none       /opt/homebrew/bin/python3.13
cpython-3.12.8-macos-aarch64-none        /usr/local/bin/python3.12

特定バージョンでプロジェクトを作成:

uv init my-project --python 3.13

既存プロジェクトでPythonバージョンをピン:

uv python pin 3.12

これで.python-versionファイルが生成され、チーム全員が同じPythonバージョンを使うようになる。

Step 6: チーム協業とCI/CDでの活用

uv.lockファイルをgitにコミットする。このファイルがあればどんな環境でも完全に同一のパッケージバージョンでインストールされる。

チームメンバーやCIでプロジェクトをクローンした後:

git clone <repo-url>
cd my-project
uv sync

今日実際にテストした結果 — .venvを削除してuv syncを実行:

Using CPython 3.11.12
Creating virtual environment at: .venv
Resolved 21 packages in 0.66ms
Installed 19 packages in 29ms

0.074秒。キャッシュがあればこのくらいだ。

uv syncの実行ログ: 19パッケージを0.074秒でインストール

GitHub Actions設定例:

name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install uv
        uses: astral-sh/setup-uv@v4
        with:
          version: "0.11.11"
      
      - name: Set up Python
        run: uv python install
      
      - name: Install dependencies
        run: uv sync --all-extras --dev
      
      - name: Run tests
        run: uv run pytest

PythonでMCPサーバーを構築する際も同じCIパターンが使える。FastMCPの依存関係をuv add fastmcpで追加し、GitHub Actionsでuv syncインストールすれば一貫したビルド環境を維持できる。

uv toolでCLIツールを管理する

uvはパッケージマネージャー以外にCLIツールのインストールも担う。pipxの役割を置き換えるものだ。

# ruffをグローバルCLIツールとしてインストール
uvx ruff check .

# インストールなしで一回限りの実行（npx方式）
uvx --from httpie http https://api.anthropic.com/v1/models

# 恒久インストール
uv tool install ruff
uv tool install black

uvxはインストールなしで即座に実行する方式だ。特定バージョンのツールを使う必要がある場合:

uvx ruff@0.4.0 check .       # バージョン指定
uvx --python 3.12 mypy .     # Python バージョン指定

AI開発でよく使うツールのインストール例:

uv tool install ruff          # コードリンター/フォーマッター
uv tool install mypy          # 型チェック
uv tool install pytest        # テスト実行
uv tool install pre-commit    # gitフック管理

実務で遭遇するエッジケース

既存のrequirements.txtプロジェクトをuvに移行する場合:

# requirements.txtのある既存プロジェクト
uv pip install -r requirements.txt

uvはpipサブコマンドもサポートする。完全移行が難しい状況でもuv pip installで既存ワークフローと併用できる。

開発専用依存関係の管理:

# 開発用グループを追加
uv add --dev pytest ruff mypy

# 本番インストール時にdevを除外
uv sync --no-dev

Anthropic SDKのオプション依存関係:

# Amazon Bedrock サポートを追加
uv add "anthropic[bedrock]"

# Vertex AI (GCP) サポートを追加
uv add "anthropic[vertex]"

依存関係ツリーとデバッグ

どのパッケージがなぜインストールされたか把握するには:

uv tree

出力:

claude-agent-demo v0.1.0
├── anthropic v0.100.0
│   ├── anyio v4.13.0
│   ├── httpx v0.28.1
│   ├── pydantic v2.13.4
│   └── ...
└── openai v2.35.1
    └── ...

pip showよりはるかに直感的だ。(*)表示はすでに他のパッケージと共有中であることを意味する。

パッケージを削除する場合:

uv remove openai

ロックファイルも自動で更新される。

正直なところ — uvの惜しい点

パフォーマンスだけ見ればほぼ完璧なツールだが、いくつか注意すべき点がある。

第一に、エコシステムの成熟度。uvは2024年に登場し、2026年現在v0.11まで来た。まだv0.xだ。個人プロジェクトや新規プロジェクトには強くお勧めするが、大規模な組織が既存のPoetry/pipワークフローを切り替える場合、チーム全体の学習コストを考慮する必要がある。

第二に、condaエコシステムとの互換性。torch、CUDA、tensorflowなどのMLライブラリをcondaチャンネルからインストールしなければならないケースがある。uvはPyPIベースのため、conda-forgeパッケージを直接インストールできない。純粋なPyPI依存関係だけなら問題ないが、CUDAバージョン合わせが必要なディープラーニングプロジェクトでは、まだcondaを併用しなければならない状況が生じる。

第三に、uv runへの慣れ。python main.pyの代わりにuv run main.pyと打つ習慣に変える必要がある。チームメンバーがsource .venv/bin/activateを忘れてシステムPythonでスクリプトを実行するミスを防ぐ効果はあるのだが。

LLMコーディング環境の最適化を扱った記事でも同様の観察をしたが、ツール自体よりチームの習慣変更の方が難しい。

まとめ: すぐ使えるコマンドレシピ

# 新しいAIプロジェクト開始
uv init my-ai-project
cd my-ai-project

# Claude SDKインストール
uv add anthropic python-dotenv

# 複数SDKを一度に追加
uv add anthropic openai httpx

# スクリプト実行（venvアクティベート不要）
uv run main.py

# チーム同期（uv.lockベース）
uv sync

# Pythonバージョン指定
uv init my-project --python 3.13

# 依存関係ツリー確認
uv tree

# パッケージ削除
uv remove openai

# uv自体の更新
uv self update

私は今、新しいAIプロジェクトを始めるとき、ほぼ自動的にuv initと打っている。pipに戻る理由が見つからない。condaが必須のMLプロジェクトではまだ選択の余地が必要だが。

0.874秒は単なる速度の話ではない。実験を頻繁にするほど、実験ごとの摩擦が少ないほど、より多くを試みるようになる。それが結局より良いコードにつながる。

他の言語で読む

この記事は役に立ちましたか？

より良いコンテンツを作成するための力になります。コーヒー一杯で応援してください。

著者について

jw

Kim Jangwook

AI/LLM専門フルスタック開発者

10年以上のWeb開発経験を活かし、AIエージェントシステム、LLMアプリケーション、自動化ソリューションを構築しています。Claude Code、MCP、RAGシステムの実践的な知見を共有します。

GitHub LinkedIn X (Twitter) プロフィールを見る

関連記事

ブログリストへ