python-uv

Python uv

概要

uv は Rust で記述された非常に高速な Python パッケージおよびプロジェクトマネージャーで、pip、pip-tools、pipx、poetry、pyenv、virtualenv を置き換えるように設計されています。プロジェクト管理、依存関係の解決、Python バージョン管理、ツールの実行を統合して提供し、従来のツールと比べて 10～100 倍の速度向上を実現します。

主な機能： プロジェクトの初期化、依存関係のロックと同期、Python バージョン管理、PEP 723 によるインラインスクリプト依存関係、uvx を使った一時的なツール実行、ロックファイルを共有するモノレポのワークスペース、パッケージのビルドと公開。

使用する場面： Python プロジェクトの初期化、依存関係の管理、仮想環境、Python バージョンの固定、インライン依存関係を含むスクリプトの実行、モノレポのワークスペース、ツールの実行、パッケージの公開。

使用しない場面： Python 以外のプロジェクト、システムレベルのバイナリ依存関係を持つ conda 管理の科学計算環境、従来の setup.py のみを使うワークフローに固定されたプロジェクト。

クイックリファレンス

パターン	コマンド／API	主なポイント
プロジェクトを初期化	uv init	pyproject.toml と .python-version を作成します
ライブラリを初期化	uv init --lib	py.typed を含む src/ レイアウトを作成します
スクリプトを初期化	uv init --script example.py	PEP 723 のインラインメタデータスクリプトです
依存関係を追加	uv add requests	pyproject.toml に追加し、ロックファイルを更新します
開発用依存関係を追加	uv add --dev pytest	[dependency-groups] の dev グループに追加します
グループ依存関係を追加	uv add --group docs mkdocs	カスタムの依存関係グループです
オプション依存関係を追加	uv add --optional postgres psycopg	ライブラリ向けのオプションの追加パッケージです
依存関係を削除	uv remove requests	pyproject.toml とロックファイルから削除します
依存関係をロック	uv lock	uv.lock を作成／更新します
ロックファイル内をアップグレード	uv lock --upgrade-package requests	対象を指定して依存関係をアップグレードします
環境を同期	uv sync	ロックされた依存関係を .venv にインストールします
CI 用に同期	uv sync --locked	ロックファイルが古い場合は失敗します
フローズンで同期	uv sync --frozen	ロックファイルの検証をスキップします
コマンドを実行	uv run python app.py	プロジェクトの仮想環境で実行します
スクリプトを実行	uv run script.py	PEP 723 のインライン依存関係に対応します
パッケージ内で実行	uv run --package api pytest	ワークスペース固有の実行です
Python をインストール	uv python install 3.13	Python のバージョンをダウンロードして管理します
Python のバージョンを固定	uv python pin 3.12	.python-version ファイルを書き込みます
Python の一覧を表示	uv python list	利用可能なバージョンとインストール済みのバージョンを表示します
ツールを実行	uvx ruff check .	一時的なツール実行です
プラグイン付きでツールを実行	uvx --with mkdocs-material mkdocs	追加パッケージを含む一時的なツールです
ツールをインストール	uv tool install ruff	ツールをグローバルに継続してインストールします
ワークスペース	[tool.uv.workspace]	モノレポの複数パッケージに対応します
パッケージをビルド	uv build	dist/ に sdist と wheel を作成します
公開	uv publish	トラステッドパブリッシングで PyPI にアップロードします
依存関係をエクスポート	uv export --format requirements-txt	ロックファイルから requirements.txt を生成します

よくある間違い

間違い	正しいパターン
uv プロジェクト内で pip install を使う	uv add を使って pyproject.toml 経由で管理する
uv run の前に手動で venv を有効化する	uv run が venv の有効化を自動的に処理する
.venv/ をバージョン管理にコミットする	.venv/ を .gitignore に追加し、uv.lock をコミットする
uv.lock をコミットしない	再現可能なビルドのため、必ず uv.lock をコミットする
CI で --locked を付けずに uv sync を使う	uv sync --locked により、ロックファイルと pyproject.toml の一致を保証する
定期的に uv lock --upgrade を実行する	意図した場合にのみアップグレードし、対象を絞った更新には --upgrade-package を使う
pip と uv の依存関係管理を混在させる	プロジェクトでは一貫してどちらか一方のツールを使う
プロジェクトの依存関係に uv pip install を使う	管理対象のプロジェクトでは uv add／uv sync を使う
Docker ビルドで --frozen を付け忘れる	uv sync --frozen はロックファイルの検証を省略し、ビルドを高速化する
uv プロジェクトで手動で venv を作成する	uv sync が .venv を自動的に作成、管理する
新規プロジェクトに setup.py を使う	最新のビルドバックエンドと pyproject.toml を使う
ライブラリで py.typed を使わない	uv init --lib に含まれており、型付きパッケージには必須です

委任

• プロジェクトのひな形作成：Explore エージェントを使います
• 依存関係の監査：Task エージェントを使います
• コードレビュー：code-reviewer エージェントに委任します

docker スキルが利用できる場合は、コンテナ化のパターンを委任します。 github-actions スキルが利用できる場合は、CI/CD パイプラインの設定を委任します。 api-testing スキルが利用できる場合は、API テストのパターンを委任します。 sentry-setup-logging スキルが利用できる場合は、エラー監視の設定を委任します。 pino-logging スキルが利用できる場合は、Node.js のログ記録パターンを委任します（Python の同等機能については、ここで structlog を扱います）。

参考資料

• プロジェクト管理と pyproject.toml の設定
• 依存関係管理、ロックファイル、グループ
• Python のバージョン管理と仮想環境
• スクリプト、インライン依存関係、ツール管理
• モノレポ向けのワークスペースサポート
• FastAPI ウェブフレームワークのパターン
• Pydantic による検証とデータモデリング
• asyncio を使った非同期処理のパターン
• mypy と pyright による型チェック
• pytest によるテスト
• structlog によるログ記録
• typer による CLI アプリケーション
• Docker との統合と公開