uv-package-manager

UV パッケージマネージャーのスキル

有効化するタイミング

次の場合にこのスキルを有効にします：

• 新しい Python プロジェクトを作成するとき
• 依存関係を追加または削除するとき
• Python スクリプトやツールを実行するとき
• 仮想環境を管理するとき
• Python のバージョン管理を設定するとき

UV を使う理由

• pip より 10～100 倍高速（Rust による実装）
• 統合ツール — pip、pip-tools、poetry、pyenv、virtualenv を置き換えます
• 信頼性 — 再現可能なビルドのためのロックファイル
• モダン — 現在の Python ワークフロー向けに構築されています

クイックコマンド

# Project Management
uv init                      # Create new project
uv init --package my-lib     # Create installable package

# Dependencies
uv add requests              # Add dependency
uv add --dev pytest          # Add dev dependency
uv remove package-name       # Remove dependency

# Running Code
uv run script.py             # Run Python script
uv run pytest                # Run installed tool
uv run python -m module      # Run module

# Environment
uv sync                      # Sync dependencies
uv sync --frozen             # Sync without updating lock
uv lock                      # Update lock file
uv python install 3.12       # Install Python version

プロジェクトの作成

# Standard project
uv init my-project
cd my-project

# Package project (for libraries)
uv init --package my-library

# Specify Python version
uv init --python 3.11

作成される構成

my-project/
├── .python-version    # Python version
├── pyproject.toml     # Project config
├── .venv/             # Virtual environment (auto-created)
└── hello.py           # Sample script

依存関係の追加

# Basic add
uv add requests fastapi uvicorn

# With version constraints
uv add "django>=4.2,<5.0"
uv add "requests==2.31.0"
uv add "fastapi[all]"

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

# From git
uv add --git https://github.com/user/repo --branch develop

スクリプトの実行

# Run Python script
uv run script.py

# Run with arguments
uv run script.py --input data.csv

# Run dev tools
uv run pytest tests/ -v
uv run black .
uv run ruff check .

# Run with temporary dependency
uv run --with httpx fetch_data.py

# Start Python REPL
uv run python

仮想環境

UV は仮想環境を自動的に管理します：

# Created automatically on first use
uv sync          # First sync
uv add package   # First package add
uv run script.py # First run

# Manual creation
uv venv
uv venv --python 3.11

# Manual activation (rarely needed)
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

ロックファイル

# Generate/update lock file
uv lock

# Sync from lock (normal)
uv sync

# Sync without updating (CI/CD)
uv sync --frozen

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

# ALWAYS commit these files:
# - pyproject.toml
# - uv.lock
# - .python-version

Python のバージョン管理

# List available versions
uv python list

# Install specific version
uv python install 3.12

# Set project version
echo "3.12" > .python-version

pip からの移行

# Import requirements.txt
uv init my-project
cd my-project
uv add -r requirements.txt

# Import dev requirements
uv add --dev -r requirements-dev.txt

pyproject.toml の一般的な構成

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.100.0",
    "uvicorn>=0.20.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
]

ベストプラクティス

すること ✅

• uv.lock と .python-version をコミットする
• 依存関係にセマンティックバージョニングを使用する
• 開発ツールには --dev を使用する
• 手動での有効化の代わりに uv run を使用する
• CI/CD では --frozen を使用する

しないこと ❌

• .venv/ ディレクトリをコミットする
• バージョン制約に * を使用する
• 同じプロジェクトで pip と uv を併用する
• 変更後のロックファイルの更新を省略する

トラブルシューティング

# Clear cache
uv cache clean

# Verbose mode for debugging
uv --verbose add package

# Regenerate lock
uv lock
uv sync

関連リソース

Docker の統合パターン、モノレポ向けのワークスペースサポート、CI/CD の設定、詳細な移行ガイドを含む完全なドキュメントについては、AgentUsage/uv_usage.md を参照してください。