192 lines
8.6 KiB
Markdown
192 lines
8.6 KiB
Markdown
# \[Python] uvに関する内部ノウハウ
|
||
|
||
## 目的
|
||
|
||
Pythonの依存関係管理・仮想環境・ツール実行・Python本体のバージョン管理を、1つの高速なCLIツールで統合するための実践手順と運用の勘所をまとめる。対象ツールはRust実装の高速パッケージ/プロジェクトマネージャである「uv」。pip、pip-tools、virtualenv、pipx、pyenv、poetry等の役割を多くの場合で置き換え、開発からCI/CDまでの再現性とスピードを両立させる。([Astral Docs][1])
|
||
|
||
## 適用範囲
|
||
|
||
* 対象環境: macOS, Linux, Windows の各開発端末およびCI環境(GitHub Actions等)。([Astral Docs][1])
|
||
* 対象バージョンやサービス: uv本体はバイナリ配布があり、Homebrew・WinGet・pip等で導入可能。([Astral Docs][2])
|
||
* 前提知識や依存関係: Python一般、pyproject.toml、バージョン管理(Git)、シェル操作。pip互換の低レベルインターフェース「uv pip」も用意されるが、挙動は完全互換ではなく差異点がある。([Astral Docs][3])
|
||
|
||
---
|
||
|
||
## 実現方法の概要
|
||
|
||
uvは「プロジェクト」を単位に、pyproject.tomlで要求仕様を定義し、uv.lockに解決済みの依存バージョンを固定する。コマンド実行前にロックと環境同期を自動で行い、プロジェクトの一貫性を担保する。さらに、`uvx`や`uv tool install`でツールを隔離実行/インストールし、`uv python`でPython本体の取得・切替も一括管理できる。([Astral Docs][4])
|
||
|
||
---
|
||
|
||
## 特徴とメリット
|
||
|
||
* 高速: pip比10〜100倍の高速化を狙った設計。単一バイナリ配布・グローバルキャッシュなどにより開発体験を大幅に短縮。([Astral Docs][1])
|
||
* 統合: 依存解決、ロック、仮想環境、ツール実行、Python本体の管理を1コマンド体系に集約。([Astral Docs][1])
|
||
* 再現性: uv.lockによるクロスプラットフォームなロックと自動同期で環境差異を低減。([Astral Docs][5])
|
||
* 柔軟性: pip互換の「uv pip」や`requirements.txt`エクスポートも可能で、段階的移行に対応。([Astral Docs][3])
|
||
|
||
---
|
||
|
||
## セットアップ手順
|
||
|
||
1. 環境準備(インストール)
|
||
|
||
* macOS/Linux
|
||
|
||
```bash
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
# もしくは Homebrew
|
||
brew install uv
|
||
```
|
||
|
||
Windows
|
||
|
||
```powershell
|
||
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][2])
|
||
2. プロジェクト作成
|
||
|
||
```bash
|
||
uv init hello-world
|
||
cd hello-world
|
||
uv run main.py
|
||
```
|
||
|
||
初回実行で `.venv` と `uv.lock` が作成される。`uv.lock` はVCSにコミットする。([Astral Docs][5])
|
||
3. 依存追加と同期
|
||
|
||
```bash
|
||
uv add fastapi uvicorn
|
||
uv lock # 明示的にロックを更新
|
||
uv sync # ロックに従って環境を同期
|
||
```
|
||
|
||
uvは`uv run`時にもロック/同期を自動実行する。([Astral Docs][4])
|
||
4. Python本体の管理(任意)
|
||
|
||
```bash
|
||
# 複数版インストール
|
||
uv python install 3.10 3.11 3.12
|
||
# プロジェクトに使用する版をピン留め
|
||
uv python pin 3.11
|
||
```
|
||
|
||
`.python-version` を生成し、以後の環境作成に使用される。([Astral Docs][1])
|
||
5. 動作確認(アプリ起動例)
|
||
|
||
```bash
|
||
uv run -- uvicorn app:app --reload --port 3000
|
||
# 仮想環境を有効化して手動実行する場合
|
||
uv sync && source .venv/bin/activate && uvicorn app:app --reload --port 3000
|
||
```
|
||
|
||
`uv run`は実行前にロックと環境の整合を保証する。([Astral Docs][5])
|
||
|
||
## 使い方
|
||
|
||
* 基本的な利用例(依存の追加/更新/削除)
|
||
|
||
```bash
|
||
uv add "requests==2.32.*"
|
||
uv remove requests
|
||
uv lock --upgrade-package requests
|
||
```
|
||
|
||
依存の追加や特定パッケージのみのアップグレードが可能。([Astral Docs][5])
|
||
|
||
* dependency-groups と extras
|
||
|
||
```toml
|
||
# 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][4])
|
||
|
||
* ツール実行とインストール
|
||
|
||
```bash
|
||
# 一時環境で実行(= pipx相当)
|
||
uvx ruff@latest check
|
||
# ツールをユーザー環境にインストール
|
||
uv tool install ruff
|
||
ruff --version
|
||
```
|
||
|
||
`uvx`は`uv tool run`のエイリアス。ツールはプロジェクト環境と分離して管理される。([Astral Docs][6])
|
||
|
||
* pip互換インターフェースの活用(段階的移行)
|
||
|
||
```bash
|
||
# 既存 requirements.txt を高速に同期
|
||
uv venv
|
||
uv pip sync requirements.txt
|
||
# requirements をロック生成
|
||
uv pip compile requirements.in -o requirements.txt
|
||
```
|
||
|
||
`uv pip`は低レベル操作向けで、完全互換ではない点に留意。([Astral Docs][3])
|
||
|
||
* CIでの利用(GitHub Actions例)
|
||
|
||
```yaml
|
||
- 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][7])
|
||
|
||
---
|
||
|
||
## 制限・注意点
|
||
|
||
* pip完全互換ではない: `uv pip`は名前のとおり低レベル操作を提供するが、挙動差があるため複雑なケースではドキュメントを確認する。([Astral Docs][3])
|
||
* 自動ロック/同期の制御: 既定で`uv run`等はロック/同期を自動実行する。固定したい場合は`--locked`や`--frozen`、同期抑止は`--no-sync`を利用する。([Astral Docs][4])
|
||
* Python版の可用性: uvの各リリースごとに利用可能なPython版リストが固定される場合がある。新しいPythonを入れる前にuv自体の更新が必要なことがある。([Astral Docs][8])
|
||
* ツール実行の選択: プロジェクトに依存するテスト系(例: pytest, mypy)は`uvx`ではなく`uv run`で実行する。`uvx`はプロジェクトから隔離された一時環境で動く。([Astral Docs][6])
|
||
* エクスポートの使い分け: 他ツール連携のため`uv export --format requirements-txt`は可能だが、基本は`uv.lock`単独運用が推奨。([Astral Docs][4])
|
||
|
||
---
|
||
|
||
## 関連リンク
|
||
|
||
* 公式トップ/概要・Highlights・コマンド早見: uv docs ([Astral Docs][1])
|
||
* インストール方法(Homebrew, WinGet, pip/pipx, Self update 他): Installing uv ([Astral Docs][2])
|
||
* プロジェクト運用(uv init, add, run, uv.lock, .venv): Working on projects ([Astral Docs][5])
|
||
* ロック/同期の概念と運用(--locked/--frozen/--no-sync, dev群, export): Locking and syncing ([Astral Docs][4])
|
||
* ツール実行/インストール(uvx, uv tool install, --from, extras): Using tools ([Astral Docs][6])
|
||
* pip互換インターフェースの考え方と注意点: The pip interface ([Astral Docs][3])
|
||
* GitHub Actionsでの利用(公式setup-uv, キャッシュ, Python設定): Using uv in GitHub Actions ([Astral Docs][7])
|
||
|
||
---
|
||
|
||
## 結論
|
||
|
||
uvは「速い」「一貫性がある」「運用が単純」の3点を同時に満たす実用的な選択肢である。日常開発では`uv add`→`uv run`で迷いなく進め、CIでは`uv sync --locked`で再現環境を固定し、ツールは`uvx`や`uv tool install`で隔離管理する。既存資産が多い場合は`uv pip`と`uv export`で段階的に移行しつつ、最終的には`uv.lock`中心の運用に統一することを推奨する。([Astral Docs][4])
|
||
|
||
[1]: https://docs.astral.sh/uv/ "uv"
|
||
[2]: https://docs.astral.sh/uv/getting-started/installation/ "Installation | uv"
|
||
[3]: https://docs.astral.sh/uv/pip/ "Index | uv"
|
||
[4]: https://docs.astral.sh/uv/concepts/projects/sync/ "Locking and syncing | uv"
|
||
[5]: https://docs.astral.sh/uv/guides/projects/ "Working on projects | uv"
|
||
[6]: https://docs.astral.sh/uv/guides/tools/ "Using tools | uv"
|
||
[7]: https://docs.astral.sh/uv/guides/integration/github/ "Using uv in GitHub Actions | uv"
|
||
[8]: https://docs.astral.sh/uv/concepts/python-versions/?utm_source=chatgpt.com "Python versions | uv - Astral Docs"
|