uv-package-manager

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

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

このスキルを使う場面

• 新しい 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 と従来のツールの比較

• pip との比較：10～100 倍高速で、リゾルバーの性能も優れています
• pip-tools との比較：より高速で、シンプルかつ使いやすいです
• poetry との比較：より高速で、独自の方針を押し付けず、軽量です
• conda との比較：より高速で、Python に特化しています

インストール

クイックインストール

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

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

# Using pip (if you already have Python)
pip install uv

# Using Homebrew (macOS)
brew install uv

# Using cargo (if you have Rust)
cargo install --git https://github.com/astral-sh/uv uv

インストールの確認

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

高度なワークフロー

パターン 12：モノレポのサポート

# Project structure
# monorepo/
#   packages/
#     package-a/
#       pyproject.toml
#     package-b/
#       pyproject.toml
#   pyproject.toml (root)

# Root pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

# Install all workspace packages
uv sync

# Add workspace dependency
uv add --path ./packages/package-a

パターン 13：CI/CD との統合

# .github/workflows/test.yml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v2
        with:
          enable-cache: true

      - name: Set up Python
        run: uv python install 3.12

      - name: Install dependencies
        run: uv sync --all-extras --dev

      - name: Run tests
        run: uv run pytest

      - name: Run linting
        run: |
          uv run ruff check .
          uv run black --check .

パターン 14：Docker との統合

# Dockerfile
FROM python:3.12-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Set working directory
WORKDIR /app

# Copy dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies
RUN uv sync --frozen --no-dev

# Copy application code
COPY . .

# Run application
CMD ["uv", "run", "python", "app.py"]

最適化されたマルチステージビルド：

# Multi-stage Dockerfile
FROM python:3.12-slim AS builder

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

# Install dependencies to venv
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-editable

# Runtime stage
FROM python:3.12-slim

WORKDIR /app

# Copy venv from builder
COPY --from=builder /app/.venv .venv
COPY . .

# Use venv
ENV PATH="/app/.venv/bin:$PATH"

CMD ["python", "app.py"]

パターン 15：ロックファイルのワークフロー

# Create lockfile (uv.lock)
uv lock

# Install from lockfile (exact versions)
uv sync --frozen

# Update lockfile without installing
uv lock --no-install

# Upgrade specific package in lock
uv lock --upgrade-package requests

# Check if lockfile is up to date
uv lock --check

# Export lockfile to requirements.txt
uv export --format requirements-txt > requirements.txt

# Export with hashes for security
uv export --format requirements-txt --hash > requirements.txt

パフォーマンスの最適化

パターン 16：グローバルキャッシュの使用

# UV automatically uses global cache at:
# Linux: ~/.cache/uv
# macOS: ~/Library/Caches/uv
# Windows: %LOCALAPPDATA%\uv\cache

# Clear cache
uv cache clean

# Check cache size
uv cache dir

パターン 17：並列インストール

# UV installs packages in parallel by default

# Control parallelism
uv pip install --jobs 4 package1 package2

# No parallel (sequential)
uv pip install --jobs 1 package

パターン 18：オフラインモード

# Install from cache only (no network)
uv pip install --offline package

# Sync from lockfile offline
uv sync --frozen --offline

他のツールとの比較

uv と pip の比較

# pip
python -m venv .venv
source .venv/bin/activate
pip install requests pandas numpy
# ~30 seconds

# uv
uv venv
uv add requests pandas numpy
# ~2 seconds (10-15x faster)

uv と poetry の比較

# poetry
poetry init
poetry add requests pandas
poetry install
# ~20 seconds

# uv
uv init
uv add requests pandas
uv sync
# ~3 seconds (6-7x faster)

uv と pip-tools の比較

# pip-tools
pip-compile requirements.in
pip-sync requirements.txt
# ~15 seconds

# uv
uv lock
uv sync --frozen
# ~2 seconds (7-8x faster)

一般的なワークフロー

パターン 19：新しいプロジェクトの開始

# Complete workflow
uv init my-project
cd my-project

# Set Python version
uv python pin 3.12

# Add dependencies
uv add fastapi uvicorn pydantic

# Add dev dependencies
uv add --dev pytest black ruff mypy

# Create structure
mkdir -p src/my_project tests

# Run tests
uv run pytest

# Format code
uv run black .
uv run ruff check .

パターン 20：既存プロジェクトの保守

# Clone repository
git clone https://github.com/user/project.git
cd project

# Install dependencies (creates venv automatically)
uv sync

# Install with dev dependencies
uv sync --all-extras

# Update dependencies
uv lock --upgrade

# Run application
uv run python app.py

# Run tests
uv run pytest

# Add new dependency
uv add new-package

# Commit updated files
git add pyproject.toml uv.lock
git commit -m "Add new-package dependency"

ツールとの統合

パターン 21：Pre-commit フック

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: uv-lock
        name: uv lock
        entry: uv lock
        language: system
        pass_filenames: false

      - id: ruff
        name: ruff
        entry: uv run ruff check --fix
        language: system
        types: [python]

      - id: black
        name: black
        entry: uv run black
        language: system
        types: [python]

パターン 22：VS Code との統合

// .vscode/settings.json
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["-v"],
  "python.linting.enabled": true,
  "python.formatting.provider": "black",
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true
  }
}

トラブルシューティング

よくある問題

# Issue: uv not found
# Solution: Add to PATH or reinstall
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

# Issue: Wrong Python version
# Solution: Pin version explicitly
uv python pin 3.12
uv venv --python 3.12

# Issue: Dependency conflict
# Solution: Check resolution
uv lock --verbose

# Issue: Cache issues
# Solution: Clear cache
uv cache clean

# Issue: Lockfile out of sync
# Solution: Regenerate
uv lock --upgrade

ベストプラクティス

プロジェクトのセットアップ

1. 再現性を確保するため、必ずロックファイルを使用します
2. .python-version で Python のバージョンを固定します
3. 開発用の依存関係と本番用の依存関係を分けます
4. venv を有効化する代わりに uv run を使用します
5. バージョン管理に uv.lock をコミットします
6. ビルドの一貫性を保つため、CI では --frozen を使用します
7. 高速化のために グローバルキャッシュを活用します
8. モノレポでは ワークスペースを使用します
9. 互換性を保つために requirements.txt にエクスポートします
10. 最新の機能を利用できるよう、uv を最新の状態に保ちます

パフォーマンスのヒント

# Use frozen installs in CI
uv sync --frozen

# Use offline mode when possible
uv sync --offline

# Parallel operations (automatic)
# uv does this by default

# Reuse cache across environments
# uv shares cache globally

# Use lockfiles to skip resolution
uv sync --frozen  # skips resolution

移行ガイド

pip + requirements.txt からの移行

# Before
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# After
uv venv
uv pip install -r requirements.txt
# Or better:
uv init
uv add -r requirements.txt

Poetry からの移行

# Before
poetry install
poetry add requests

# After
uv sync
uv add requests

# Keep existing pyproject.toml
# uv reads [project] and [tool.poetry] sections

pip-tools からの移行

# Before
pip-compile requirements.in
pip-sync requirements.txt

# After
uv lock
uv sync --frozen

コマンドリファレンス

基本的なコマンド

# Project management
uv init [PATH]              # Initialize project
uv add PACKAGE              # Add dependency
uv remove PACKAGE           # Remove dependency
uv sync                     # Install dependencies
uv lock                     # Create/update lockfile

# Virtual environments
uv venv [PATH]              # Create venv
uv run COMMAND              # Run in venv

# Python management
uv python install VERSION   # Install Python
uv python list              # List installed Pythons
uv python pin VERSION       # Pin Python version

# Package installation (pip-compatible)
uv pip install PACKAGE      # Install package
uv pip uninstall PACKAGE    # Uninstall package
uv pip freeze               # List installed
uv pip list                 # List packages

# Utility
uv cache clean              # Clear cache
uv cache dir                # Show cache location
uv --version                # Show version

リソース

• 公式ドキュメント: https://docs.astral.sh/uv/
• GitHub リポジトリ: https://github.com/astral-sh/uv
• Astral ブログ: https://astral.sh/blog
• 移行ガイド: https://docs.astral.sh/uv/guides/
• 他のツールとの比較: https://docs.astral.sh/uv/pip/compatibility/

ベストプラクティスのまとめ

1. 新しいプロジェクトでは uv を使用する - uv init で開始します
2. ロックファイルをコミットする - 再現可能なビルドを実現します
3. Python のバージョンを固定する - .python-version を使用します
4. uv run を使用する - 仮想環境を手動で有効化するのは避けます
5. キャッシュを活用する - uv にグローバルキャッシュを管理させます
6. CI では --frozen を使用する - 正確に再現します
7. uv を最新の状態に保つ - 開発の進みが速いプロジェクトです
8. ワークスペースを使用する - モノレポのプロジェクトに適しています
9. 互換性のためにエクスポートする - 必要に応じて requirements.txt を生成します
10. ドキュメントを読む - uv は機能が豊富で、進化を続けています