uv で Python パッケージ管理を始める（pip / Poetry との比較）

概要

Python のパッケージ管理は長らく pip + venv + requirements.txt が定番でしたが、依存解決の遅さ・ロックの弱さ・Python 本体のバージョン管理を別ツールに頼る点が課題でした。uv は Rust 製の高速なパッケージ／プロジェクトマネージャで、これらを1つのバイナリに統合します。本記事では uv を手を動かしながら導入し、pip / Poetry との違いを整理します。

uv とは何か

uv は Ruff の開発元（Astral）が開発する Python 向けツールで、次の役割を統合しています。

• 仮想環境の作成（venv 相当）
• 依存解決・インストール（pip 相当）
• ロックファイル・プロジェクト管理（Poetry / pip-tools 相当）
• Python 本体のインストール・切替（pyenv 相当）
• CLI ツールの隔離実行（pipx 相当）

Rust 実装＋グローバルキャッシュにより、依存解決とインストールが高速です。

インストール

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

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# pipx / Homebrew でも可
pipx install uv
brew install uv

確認とアップデート:

uv --version
uv self update

ハンズオン1: プロジェクトを作る

uv init my-app
cd my-app

生成物:

my-app/
├── .python-version
├── pyproject.toml
├── README.md
└── main.py

pyproject.toml（抜粋）:

[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = []

ハンズオン2: 依存を追加する

uv add requests               # 本番依存
uv add --dev pytest ruff      # 開発依存
uv add "requests>=2.31,<3"    # バージョン指定
uv remove requests            # 削除

uv add 1回で「.venv 作成 → 依存解決 → pyproject.toml 更新 → uv.lock 更新 → インストール」までまとめて実行されます。

ハンズオン3: コードを実行する

uv run python main.py
uv run pytest
uv run ruff check .

uv run は実行前にロックと環境を自動同期するため、仮想環境の有効化を省けます。従来どおりの有効化も可能です。

source .venv/bin/activate     # Windows: .venv\Scripts\activate
python main.py

ハンズオン4: ロックと同期

uv lock            # pyproject.toml から uv.lock を生成・更新
uv sync            # uv.lock どおりに .venv を揃える

CI では次のように「ロックが最新であること」を検証してから固定同期すると安全です。

uv lock --check    # lock がずれていたら失敗
uv sync --frozen   # lock を書き換えず、その内容で同期

uv.lock は Git にコミットして共有します。

ハンズオン5: Python 本体のバージョン管理

uv python list             # 利用可能な Python 一覧
uv python install 3.12     # 取得
uv python pin 3.12         # .python-version を更新

uv run / uv sync は .python-version と requires-python を見て、必要な Python を自動で用意します（pyenv が不要になるケースが多い）。

ハンズオン6: CLI ツールの隔離実行（pipx 相当）

uvx ruff check .           # 一時実行（インストールを残さない）
uv tool install ruff       # 恒久インストール

pip / Poetry との比較

観点	pip + venv	Poetry	uv
仮想環境	別途 venv	内蔵	内蔵
ロック	requirements.txt（手運用/pip-tools）	poetry.lock	uv.lock
Python 本体管理	別ツール	別ツール	内蔵
CLI ツール隔離	pipx 別途	―	uvx 内蔵
実装 / 速度	Python / 標準	Python / 標準	Rust / 高速

使い分けの目安:

• 1ファイル動かすだけ → pip で十分
• Poetry 資産に厚く乗っている → 継続も合理的
• 依存・CI・Python バージョン・CLI まで一本化して速くしたい → uv

既存プロジェクトからの移行

requirements.txt から

uv add -r requirements.txt
uv pip compile requirements.txt -o requirements.lock

uv pip install / uv pip freeze のように、pip の高速な代替バックエンドとして使う道もあります。

Poetry から

[tool.poetry] に書かれた依存を PEP 621 の [project.dependencies] に移し替え、uv lock でロックを生成し直すのが基本方針です。

確認方法

uv --version
uv run python -c "import sys; print(sys.executable)"  # .venv を指していれば OK
uv tree                                               # 依存ツリー

注意点

• サブコマンドはバージョンで変わるため、uv help と uv --version を正とする
• uv.lock は必ずコミットする（再現性の要）
• uv sync は環境を「ロックに揃える」ため、ロック外の手動インストールは消える可能性がある。追加は uv add に統一する
• 企業内プロキシ／プライベートインデックスでは UV_INDEX_URL や [[tool.uv.index]] の設定が必要になることがある
• pip 互換は完全ではないため、特殊オプション・プラグイン依存は事前検証する

まとめ

• uv は仮想環境・依存・ロック・Python 本体・CLI ツールを1バイナリに統合した高速ツール
• 新規プロジェクトは uv init → uv add → uv run の3コマンドで回り始める
• 再現性は uv.lock + uv sync（CI では --frozen / --check）で担保する
• pip / Poetry を全否定するものではなく、「一本化」と「速度」を取りたいときの強力な選択肢

まずは小さな既存プロジェクトを1つ uv に載せ替えて、uv sync の速さと uv run の手軽さを体感してみてください。