uv で Python 環境構築

Python の依存関係解決・インストール・仮想環境・Python 本体の管理を、1 本の高速バイナリでまるっと扱えるのが Astral 社の uv です。pip/venv より数十倍速いケースも多く、pyproject.toml ベースで再現可能な環境を構築できます。

特徴（ざっくり）

• 高速解決・インストール: Rust 製のソルバ＋キャッシュで爆速
• 再現性の高いロックファイル: uv.lock をコミットして同一環境を再現
• 1 コマンド運用: 仮想環境作成・実行・Python 切替まで uv で統一
• pip 互換モードも搭載: 段階的移行や既存プロジェクト対応が容易

インストール

macOS / Linux:

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

• 説明: 公式インストーラを実行して uv バイナリを配置します。完了後は uv -V で確認。

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

• 説明: 同様に PowerShell 経由でインストールします。

最短クイックスタート

1) プロジェクト初期化

uv init myapp
cd myapp

• uv init <name>: pyproject.toml・ディレクトリなどを作成して Python プロジェクトの雛形を用意
• cd myapp: 作成したプロジェクトへ移動

2) 依存関係を追加

uv add requests

• uv add <pkg>: pyproject.toml の [project] dependencies に追記し、解決・ロック・インストールを実行

3) 実行（仮想環境の有無を気にしない）

uv run python -c "import requests; print(requests.__version__)"

• uv run: プロジェクトの仮想環境（なければ自動作成）上でコマンドを実行。明示的な activate は不要

---

既存プロジェクトを同期（pyproject あり想定）

uv lock
uv sync

• uv lock: 依存関係を解決して uv.lock を生成・更新
• uv sync: uv.lock に基づいて .venv を作成し、完全同期（不要なパッケージは除去、足りないものを追加）

ポイント:

• pyproject.toml と uv.lock をリポジトリにコミットすると、CI/同僚の環境で再現性が担保されます。

仮想環境の作成と使い分け

明示的に仮想環境だけ作る

uv venv

• uv venv: プロジェクト直下に .venv を作成（デフォルト）。以降 uv run で自動利用されます。

uv venv --python 3.12

• --python <ver>: 指定バージョンの Python で仮想環境を作成（該当バージョンが未導入なら後述の uv python install を実行）

手動で有効化したい場合（任意）

source .venv/bin/activate   # macOS/Linux
# or
.\.venv\Scripts\activate    # Windows

• 説明: uv run を使うなら手動の activate は不要。従来スタイルに合わせたい場面だけ使えば OK

Python 本体の管理

uv python install 3.12

• 指定バージョンの Python を uv が管理配下にインストール

uv python list

• uv 管理下のインストール済 Python を一覧表示

コツ:

• プロジェクト側では pyproject.toml の requires-python に対応範囲を明記（例: >=3.10,<3.13）
• 仮想環境作成時に uv venv --python 3.12 でピン留めするのが実務で扱いやすい

依存関係のグループ分け（dev 等）

開発専用ツールは dev グループへ:

uv add --group dev pytest ruff

• --group <name>: dependency-groups.dev に分類して追加（本番と開発のインストールを分けやすくなる）

開発ツール込みで同期:

uv sync --group dev

• 指定グループも含めてインストール（CI では core のみ、本地では dev も、の使い分けが可能）

スクリプト実行と便利コマンド

コマンドを環境内で実行

uv run pytest -q

• 仮想環境を暗黙に使ってテストを実行。activate 不要

依存ツリーの確認

uv tree

• インストール済み依存のツリーを表示し、重複や競合の把握に役立ちます

キャッシュ管理

uv cache dir
uv cache prune

• dir: キャッシュ場所の確認
• prune: キャッシュ掃除（ディスク圧迫時に有効）

ロックとエクスポート

ロック生成・更新:

uv lock

• 依存解決の結果を uv.lock に固定。必ずコミットしましょう

requirements.txt へエクスポート（pip 向け配布などに）

uv export --format requirements.txt > requirements.txt

• uv.lock をもとにピン留め済みの requirements.txt を生成

---

pip 互換モード（段階的移行や既存運用に）

uv pip install -r requirements.txt
uv pip freeze

• uv pip install: pip と同等の UI で高速インストール（仮想環境は uv venv 済みを推奨）
• uv pip freeze: 従来と同様に固定化リストを出力

完全移行が難しいプロジェクトでも、まずは「速い pip」として導入できます。

ツール実行（グローバル or エフェメラル）

グローバルにツールを入れる:

uv tool install ruff
ruff --version

• uv tool install <pkg>: CLI ツールを隔離された環境にインストールし、直接コマンドとして使えるようにする

一時的にツールを実行（インストール不要）:

uvx ruff check .

• uvx <tool>: 実行に必要なものだけをダウンロードしてその場で実行（pipx 的な体験）

よく使うワークフロー例

新規作成〜実行まで:

uv init sample
cd sample
uv add fastapi uvicorn
uv run uvicorn sample:app --reload

• uv add: 依存を登録して即インストール
• uv run: .venv を意識せずにアプリ起動

Python バージョンを固定して開発:

uv python install 3.12
uv venv --python 3.12
uv add --group dev pytest
uv run pytest

• uv venv --python: プロジェクトごとに明示したバージョンで仮想環境を作成

トラブル対処のヒント

• システム Python と混ざる: 常に uv run、または明示的に .venv を使う
• バージョン競合で解決失敗: pyproject.toml のバージョン指定を緩める/揃える、uv tree で確認
• プロキシ環境: HTTP_PROXY/HTTPS_PROXY 環境変数を設定してから実行
• CI で再現性を担保: uv sync を使い、pyproject.toml と uv.lock をコミット

まとめ

• uv を使うと「仮想環境の作成」「依存の追加/同期」「Python 本体の導入」「高速実行」までを単一ツールで完結できます。
• 日常は uv add（依存追加）、uv sync（同期）、uv run（実行）、困ったら uv tree（可視化）を覚えれば OK。
• 再現性は uv.lock コミットで担保しましょう。pip 互換もあるので移行は段階的に。