uv-project-management

UV プロジェクト管理

UV のプロジェクト設定、依存関係、ロックファイルに関するクイックリファレンスです。

このスキルを使う場面

このスキルを使う場面...	代わりに用途を絞った関連スキルを使う場面...
日常的な依存関係管理で uv init、uv add、uv remove、uv lock、または uv sync を実行する	スクリプトまたは単発のコマンドを実行する場合 — uv-run を使います
pyproject.toml の [project] および [tool.uv] セクションを作成または編集する	git／path／editable の依存関係やワークスペースの継承を設定する場合 — uv-advanced-dependencies を使います
新しい単一パッケージの Python プロジェクトを初期設定する	リポジトリを複数パッケージのワークスペースに分割する場合 — uv-workspaces を使います

このスキルが適用される場面

• 新しい Python プロジェクトを初期化する（uv init）
• 依存関係を追加、削除、または更新する（uv add、uv remove）
• ロックファイルを管理する（uv lock）
• プロジェクトの環境を同期する（uv sync）
• pyproject.toml を設定する

スクリプトの実行については、uv-run スキルを参照してください。

クイックリファレンス

プロジェクトの初期化

# Create new project with complete structure
uv init my-project
cd my-project

# Initialize in existing directory
uv init

# Initialize with specific Python version
uv init --python 3.11 my-app

依存関係の管理

# Add dependencies
uv add requests
uv add 'flask>=2.0'
uv add 'django>=4.0,<5.0'

# Add development dependencies
uv add --dev pytest pytest-cov black

# Add optional dependency groups
uv add --group docs sphinx sphinx-rtd-theme

# Remove dependencies
uv remove requests flask

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

ロックファイルの操作

# Create/update lockfile (uv.lock)
uv lock

# Lock with upgraded packages
uv lock --upgrade-package requests
uv lock --upgrade

# Lock without installing (CI/CD)
uv lock --frozen

環境の同期

# Sync environment to lockfile
uv sync

# Sync without updating lockfile
uv sync --frozen

# Error if lockfile is out of date
uv sync --locked

プロジェクト構成

UV プロジェクトは、次の標準的な構成に従います。

my-project/
├── pyproject.toml      # Project metadata and dependencies
├── uv.lock            # Locked dependency versions
├── .venv/             # Virtual environment (auto-created)
├── README.md
└── src/
    └── my_project/
        └── __init__.py

生成される pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []

[build-system]
requires = ["uv_build>=0.9.2,<0.10.0"]
build-backend = "uv_build"

よくあるワークフロー

新しいプロジェクトを開始する

uv init my-app && cd my-app
uv add ruff pytest
uv run pytest

複数の依存関係を追加する

# Production dependencies
uv add fastapi uvicorn 'pydantic>=2.0'

# Development tooling
uv add --dev pytest pytest-cov ruff ty

# Documentation
uv add --group docs sphinx mkdocs-material

依存関係を更新する

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

# Update all dependencies
uv lock --upgrade

# Sync after update
uv sync

主な機能

• 高速：pip より 10〜100 倍高速です
• 決定論的：ロックファイルにより、再現可能なインストールを実現します
• 自動：仮想環境を作成し、管理します
• モダン：設定に pyproject.toml を使用します
• 互換性：pip、Poetry、その他のツールと連携します

関連項目

• uv-run - スクリプトの実行、一時的な依存関係、PEP 723
• uv-python-versions - Python インタープリターのバージョン管理
• uv-workspaces - モノレポおよび複数パッケージのプロジェクト
• uv-advanced-dependencies - Git、path、制約付きの依存関係
• uv-tool-management - CLI ツールをグローバルにインストールする
• python-testing - pytest でテストを実行する
• python-code-quality - ruff でリンティングとフォーマットを行う

参考資料

• 公式ドキュメント：https://docs.astral.sh/uv/
• GitHub：https://github.com/astral-sh/uv
• 詳細ガイド：このスキルのディレクトリにある REFERENCE.md を参照してください