python-common-code/docments/uv.md

# \[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"