uv チートシート

uv¹ は Rust で書かれた Python のパッケージ管理ツールである。 pip、pip-tools、virtualenv、pyenv、pipx、poetry が別々に担っていた役割を一つのコマンドにまとめ、依存解決とインストールを高速に行う。

この記事は、公式ドキュメント²を読みながら、日常的に使うコマンドを用途別にまとめた早見表である。 大きく分けて、pyproject.toml を軸にしたプロジェクト管理、単体スクリプトの実行、CLI ツールの実行と常駐、Python 本体のバージョン管理、そして pip 互換の低レベルインターフェースがある。

インストールと自己管理

curl -LsSf https://astral.sh/uv/install.sh | sh

プロジェクト管理

pyproject.toml で依存を宣言し、uv.lock で解決結果を固定し、.venv に環境を作る。 このワークフローがプロジェクト管理の中心になる。

uv run を使えば .venv を明示的に有効化する必要はないが、有効化して従来通り使うこともできる。

source .venv/bin/activate

プロジェクト直下には次のファイルが置かれる。

スクリプト実行

単体のスクリプトは、プロジェクトを作らずに実行できる。 依存はコマンドで一時的に足すか、PEP 723³ のインラインメタデータとしてスクリプト先頭に埋め込む。

uv add --script は、スクリプト先頭に依存を書いたコメントブロック（PEP 723 のインラインメタデータ）を追記する。 依存の情報がスクリプト自身に入るので、requirements.txt や pyproject.toml を別に用意しなくても、そのファイル一つで依存関係が完結する。 受け取った側は uv run example.py を実行するだけでよく、uv がこのメタデータを読んで依存を用意する。 このため、環境構築の説明なしに人へ渡したいちょっとした自動化スクリプトや、Gist のような単一ファイルの共有が主な用途になる。

書き込まれるメタデータは次の形になる。

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

シェバングに指定すれば、スクリプトを直接実行できる。

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["httpx"]
# ///
import httpx

chmod +x example.py && ./example.py

ツールの実行とインストール

ruff や black のような CLI ツールは、一時環境で実行するか、ユーザー全体にインストールして常駐させる。 uvx は一時環境での実行、uv tool install は PATH に実行ファイルを通す常駐インストールである。

uv は、import せずにシェルからコマンドとして起動するパッケージをツールと呼び、専用のコマンド群を用意している。 ruff、mypy、black のように、コードを外から検査・整形するもので、アプリの一部としては動かない。 そのためプロジェクトの依存（uv add）とは分け、プロジェクトから隔離した環境に入れる。 判断の目安は、コード中で import するなら uv add、コマンド名を打って使うだけなら uv tool である。

インストールしたツールの環境は、直接いじらず uv tool upgrade や uv tool install 経由で更新する。 uv はツール環境を直接手を加える前提で作っていないため、中の .venv に手動で pip install などをすると壊れることがある。

Python バージョンの管理

uv は Python 本体のインストールとバージョン切り替えも担う。 pyenv に相当する役割であり、uv を使うなら pyenv は不要になる。

pip 互換インターフェース

uv pip は、既存の pip / pip-tools ワークフローをそのまま高速化するための低レベルコマンド群である⁴。 プロジェクトの uv add / uv sync とは別系統で、requirements.txt を手で扱う場面や移行期に使う。

仮想環境

パッケージ操作

環境の確認

ロックと同期（pip-tools 相当）

uv pip install は既存のパッケージを残すが、uv pip sync はロックにないものを削除して環境を完全一致させる。

pip-tools 風のワークフローはこうなる。

uv pip compile requirements.in -o requirements.txt   # 依存を固定する
uv pip sync requirements.txt                          # 環境を一致させる

既存プロジェクトの移行

uv pip の主な使いどころは、すでに pip と requirements.txt で動いているプロジェクトの移行である。 uv add / uv sync のマネージド構成へは、二段階で無理なく移せる。

段階1では、既存のコマンドを uv pip に置き換えるだけにとどめる。 requirements.txt の構成はそのままで、既存の pip コマンドを uv pip に差し替えるだけでよい。 uv は pip の drop-in replacement であり、10〜100 倍の高速化が見込める⁵。

uv venv                              # python -m venv .venv の置き換え
uv pip install -r requirements.txt   # pip install -r ... の置き換え

段階2では、余裕ができてから pyproject.toml と uv.lock のマネージド構成へ引き上げる。 uv add -r が既存の requirements.txt を読み、依存を pyproject.toml に取り込み、uv.lock を生成する。

uv init --bare               # 既存ディレクトリに pyproject.toml だけ作る
uv add -r requirements.txt   # requirements.txt の中身を依存として取り込む

ここまで来れば、以降は uv add / uv sync / uv run に切り替えられ、requirements.txt は不要になる。

キャッシュとディレクトリ

使い分けの目安