[Python] uvに関する内部ノウハウ

目的

Pythonの依存関係管理・仮想環境・ツール実行・Python本体のバージョン管理を、1つの高速なCLIツールで統合するための実践手順と運用の勘所をまとめる。対象ツールはRust実装の高速パッケージ/プロジェクトマネージャである「uv」。pip、pip-tools、virtualenv、pipx、pyenv、poetry等の役割を多くの場合で置き換え、開発からCI/CDまでの再現性とスピードを両立させる。(Astral Docs)

適用範囲

対象環境: macOS, Linux, Windows の各開発端末およびCI環境(GitHub Actions等)。(Astral Docs)
対象バージョンやサービス: uv本体はバイナリ配布があり、Homebrew・WinGet・pip等で導入可能。(Astral Docs)
前提知識や依存関係: Python一般、pyproject.toml、バージョン管理(Git)、シェル操作。pip互換の低レベルインターフェース「uv pip」も用意されるが、挙動は完全互換ではなく差異点がある。(Astral Docs)

実現方法の概要

uvは「プロジェクト」を単位に、pyproject.tomlで要求仕様を定義し、uv.lockに解決済みの依存バージョンを固定する。コマンド実行前にロックと環境同期を自動で行い、プロジェクトの一貫性を担保する。さらに、uvxやuv tool installでツールを隔離実行/インストールし、uv pythonでPython本体の取得・切替も一括管理できる。(Astral Docs)

特徴とメリット

高速: pip比10〜100倍の高速化を狙った設計。単一バイナリ配布・グローバルキャッシュなどにより開発体験を大幅に短縮。(Astral Docs)
統合: 依存解決、ロック、仮想環境、ツール実行、Python本体の管理を1コマンド体系に集約。(Astral Docs)
再現性: uv.lockによるクロスプラットフォームなロックと自動同期で環境差異を低減。(Astral Docs)
柔軟性: pip互換の「uv pip」やrequirements.txtエクスポートも可能で、段階的移行に対応。(Astral Docs)

セットアップ手順

環境準備(インストール)

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
# もしくは Homebrew
brew install uv

Windows

winget install --id=astral-sh.uv -e
# もしくは PowerShell スクリプト
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

参考: pip/pipx経由やDockerイメージ、自己アップデートuv self updateも可。(Astral Docs)

プロジェクト作成
```
uv init hello-world
cd hello-world
uv run main.py
```
初回実行で .venv と uv.lock が作成される。uv.lock はVCSにコミットする。(Astral Docs)

依存追加と同期

uv add fastapi uvicorn
uv lock             # 明示的にロックを更新
uv sync             # ロックに従って環境を同期

uvはuv run時にもロック/同期を自動実行する。(Astral Docs)

Python本体の管理(任意)

# 複数版インストール
uv python install 3.10 3.11 3.12
# プロジェクトに使用する版をピン留め
uv python pin 3.11

.python-version を生成し、以後の環境作成に使用される。(Astral Docs)

動作確認(アプリ起動例)

uv run -- uvicorn app:app --reload --port 3000
# 仮想環境を有効化して手動実行する場合
uv sync && source .venv/bin/activate && uvicorn app:app --reload --port 3000

uv runは実行前にロックと環境の整合を保証する。(Astral Docs)

使い方

基本的な利用例(依存の追加/更新/削除)
```
uv add "requests==2.32.*"
uv remove requests
uv lock --upgrade-package requests
```
依存の追加や特定パッケージのみのアップグレードが可能。(Astral Docs)

dependency-groups と extras

# pyproject.toml (抜粋)
[project]
name = "sample"
version = "0.1.0"
dependencies = ["fastapi", "uvicorn"]

[dependency-groups]
dev = ["pytest", "ruff"]

# dev群を含めて同期
# dev群は既定で含まれる。除外は --no-dev
# 任意の群は --group foo, すべては --all-groups

依存群(dev等)やextrasの同期はフラグで制御できる。(Astral Docs)

ツール実行とインストール
```
# 一時環境で実行(= pipx相当)
uvx ruff@latest check
# ツールをユーザー環境にインストール
uv tool install ruff
ruff --version
```
uvxはuv tool runのエイリアス。ツールはプロジェクト環境と分離して管理される。(Astral Docs)

pip互換インターフェースの活用(段階的移行)

# 既存 requirements.txt を高速に同期
uv venv
uv pip sync requirements.txt
# requirements をロック生成
uv pip compile requirements.in -o requirements.txt

uv pipは低レベル操作向けで、完全互換ではない点に留意。(Astral Docs)

CIでの利用(GitHub Actions例)

- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v6
- run: uv python install
- run: uv sync --locked --all-extras --dev
- run: uv run pytest -q

公式のsetup-uvで導入・キャッシュ・Python設定が簡便。(Astral Docs)

制限・注意点

pip完全互換ではない: uv pipは名前のとおり低レベル操作を提供するが、挙動差があるため複雑なケースではドキュメントを確認する。(Astral Docs)
自動ロック/同期の制御: 既定でuv run等はロック/同期を自動実行する。固定したい場合は--lockedや--frozen、同期抑止は--no-syncを利用する。(Astral Docs)
Python版の可用性: uvの各リリースごとに利用可能なPython版リストが固定される場合がある。新しいPythonを入れる前にuv自体の更新が必要なことがある。(Astral Docs)
ツール実行の選択: プロジェクトに依存するテスト系(例: pytest, mypy)はuvxではなくuv runで実行する。uvxはプロジェクトから隔離された一時環境で動く。(Astral Docs)
エクスポートの使い分け: 他ツール連携のためuv export --format requirements-txtは可能だが、基本はuv.lock単独運用が推奨。(Astral Docs)

結論

uvは「速い」「一貫性がある」「運用が単純」の3点を同時に満たす実用的な選択肢である。日常開発ではuv add→uv runで迷いなく進め、CIではuv sync --lockedで再現環境を固定し、ツールはuvxやuv tool installで隔離管理する。既存資産が多い場合はuv pipとuv exportで段階的に移行しつつ、最終的にはuv.lock中心の運用に統一することを推奨する。(Astral Docs)

8.6 KiB Raw Blame History Unescape Escape