uv-package-manager

UV パッケージマネージャー

Rust で書かれた非常に高速な Python パッケージインストーラー兼リゾルバーである uv を使用した、モダンな Python プロジェクト管理と依存関係ワークフローのための包括的なガイドです。

このスキルを使用する場面

• 新しい Python プロジェクトをすばやくセットアップするとき
• pip よりも速く Python の依存関係を管理するとき
• 仮想環境を作成および管理するとき
• Python インタープリターをインストールするとき
• 依存関係の競合を効率的に解決するとき
• pip/pip-tools/poetry から移行するとき
• CI/CD パイプラインを高速化するとき
• モノレポの Python プロジェクトを管理するとき
• 再現可能なビルドのためにロックファイルを扱うとき
• Python の依存関係を含む Docker ビルドを最適化するとき

中核となる概念

1. uv とは？

• 超高速パッケージインストーラー: pip より 10～100 倍高速
• Rust で書かれている: Rust のパフォーマンスを活用
• pip のドロップイン置換: pip のワークフローと互換
• 仮想環境マネージャー: venv の作成と管理
• Python インストーラー: Python バージョンのダウンロードと管理
• リゾルバー: 高度な依存関係解決
• ロックファイル対応: 再現可能なインストール

2. 主な機能

• 驚異的に高速なインストール速度
• グローバルキャッシュによるディスク容量の効率化
• pip、pip-tools、poetry との互換性
• 包括的な依存関係解決
• クロスプラットフォーム対応（Linux、macOS、Windows）
• インストールに Python が不要
• 仮想環境のサポートを内蔵

3. UV と従来のツールの比較

• vs pip: 10～100 倍高速、より優れたリゾルバー
• vs pip-tools: より高速、よりシンプル、より良い UX
• vs poetry: より高速、主張が少なく、より軽量
• vs conda: より高速、Python に焦点

インストール

クイックインストール

# Using Homebrew (macOS or Linux)
brew install uv

# Using Cargo (if you have Rust)
cargo install --locked uv

Windows では WinGet を使用します:

winget install --id=astral-sh.uv -e

その他のサポートされているインストール方法については、公式インストールガイドを参照してください。

インストールの確認

uv --version
# uv 0.x.x

クイックスタート

新しいプロジェクトの作成

# Create new project with virtual environment
uv init my-project
cd my-project

# Or create in current directory
uv init .

# Initialize creates:
# - .python-version (Python version)
# - pyproject.toml (project config)
# - README.md
# - .gitignore

依存関係のインストール

# Install packages (creates venv if needed)
uv add requests pandas

# Install dev dependencies
uv add --dev pytest black ruff

# Install from requirements.txt
uv pip install -r requirements.txt

# Install from pyproject.toml
uv sync

仮想環境の管理

パターン 1: 仮想環境の作成

# Create virtual environment with uv
uv venv

# Create with specific Python version
uv venv --python 3.12

# Create with custom name
uv venv my-env

# Create with system site packages
uv venv --system-site-packages

# Specify location
uv venv /path/to/venv

パターン 2: 仮想環境のアクティベート

# Linux/macOS
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Or use uv run (no activation needed)
uv run python script.py
uv run pytest

パターン 3: uv run の使用

# Run Python script (auto-activates venv)
uv run python app.py

# Run installed CLI tool
uv run black .
uv run pytest

# Run with specific Python version
uv run --python 3.11 python script.py

# Pass arguments
uv run python script.py --arg value

パッケージ管理

パターン 4: 依存関係の追加

# Add package (adds to pyproject.toml)
uv add requests

# Add with version constraint
uv add "django>=4.0,<5.0"

# Add multiple packages
uv add numpy pandas matplotlib

# Add dev dependency
uv add --dev pytest pytest-cov

# Add optional dependency group
uv add --optional docs sphinx

# Add from git
uv add git+https://github.com/user/repo.git

# Add from git with specific ref
uv add git+https://github.com/user/[email protected]

# Add from local path
uv add ./local-package

# Add editable local package
uv add -e ./local-package

パターン 5: 依存関係の削除

# Remove package
uv remove requests

# Remove dev dependency
uv remove --dev pytest

# Remove multiple packages
uv remove numpy pandas matplotlib

パターン 6: 依存関係のアップグレード

# Upgrade specific package
uv add --upgrade requests

# Upgrade all packages
uv sync --upgrade

# Upgrade package to latest
uv add --upgrade requests

# Show what would be upgraded
uv tree --outdated

パターン 7: 依存関係のロック

# Generate uv.lock file
uv lock

# Update lock file
uv lock --upgrade

# Lock without installing
uv lock --no-install

# Lock specific package
uv lock --upgrade-package requests

Python バージョンの管理

パターン 8: Python バージョンのインストール

# Install Python version
uv python install 3.12

# Install multiple versions
uv python install 3.11 3.12 3.13

# Install latest version
uv python install

# List installed versions
uv python list

# Find available versions
uv python list --all-versions

パターン 9: Python バージョンの設定

# Set Python version for project
uv python pin 3.12

# This creates/updates .python-version file

# Use specific Python version for command
uv --python 3.11 run python script.py

# Create venv with specific version
uv venv --python 3.12

プロジェクト構成

パターン 10: uv での pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0.0",
    "click>=8.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]
docs = [
    "sphinx>=7.0.0",
    "sphinx-rtd-theme>=1.3.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = [
    # Additional dev dependencies managed by uv
]

[tool.uv.sources]
# Custom package sources
my-package = { git = "https://github.com/user/repo.git" }

パターン 11: 既存プロジェクトでの uv の使用

# Migrate from requirements.txt
uv add -r requirements.txt

# Migrate from poetry
# Already have pyproject.toml, just use:
uv sync

# Export to requirements.txt
uv pip freeze > requirements.txt

# Export with hashes
uv pip freeze --require-hashes > requirements.txt

Docker 統合、ロックファイル管理、パフォーマンス最適化、ツール比較、一般的なワークフロー、ツール統合、トラブルシューティング、ベストプラクティス、移行ガイド、コマンドリファレンスを含む高度なワークフローについては、references/advanced-patterns.md を参照してください。