🕶️

忙しい人のための uv チュートリアル

に公開
Python
uv
tech

※この記事は人間がアウトライン書いて、Gemini Pro2.5が書き直したものです

この記事では、個人の需要と偏見で決めたuvの使い方を紹介します。

TLDR: uvはPythonのインストールとpip installの代替だけに使えばリターン十分にあります。
TLDR: 更に忙しい人は 3. 自分用のMakefile から見てもOK

1 uv python によるバージョン管理

これまで私は、Pythonのバージョン管理や、PyTorch関連のパッケージをインストールするためにmicromambaを愛用していました。しかし、最近PyTorchチームが公式のCondaリポジトリのサポートを縮小・非推奨化する動きを見せています（※）。この状況で、Pythonのインストールだけのためにmicoromambaを使い続けるのは、少し大げさだと感じるようになりました。

2 uv pip install: pipの爆速代替

私にとってuvの最大の価値は、pipとの互換性を保ちながら劇的に高速化されたパッケージインストール機能です。

pip install は、依存関係の解決に「バックトラッキング」という処理を行うことがあり、これが時として非現実的なほど遅くなる原因でした。特に、複雑な依存関係を持つプロジェクトでは、この解決プロセスに時間単位で待たされることも珍しくありません。

uv pip installは、この問題を解決します。Rustで書かれた高速なリゾルバのおかげで、依存関係の解決とパッケージのダウンロードが驚くほど速く完了します。私にとって、uvを導入する最大の動機は、この速度にありました。

3 自分用のMakefile

私は、多くのPythonリポジトリで以下のようなMakefileを共通で使っています。make depsコマンドを実行するだけで、指定したPythonバージョンで仮想環境(venv)を作成し、requirements.txtに基づいた依存関係のインストールまでを自動で行います。

PYTHON_VER ?= 3.12

# comma separated packages
FREEZE_PY_REQ = elasticsearch

deps: venv/.deps_installed

venv/.deps_installed: venv requirements.txt
	# the most useful command of uv
	UV_PYTHON=venv uv pip install -r requirements.txt
	@echo "deps installed"
	@touch $@

upgrade-deps:
	venv/bin/pur -r requirements.txt --force --skip=$(FREEZE_PY_REQ)

venv: venv/.venv_created

venv/.venv_created: Makefile
	# the 2nd most useful command of uv. This only downloads Python when not installed by OS or uv.
	uv venv --python=$(PYTHON_VER) venv
	@touch $@

4. バージョンロックについて

私はuv.lockのような厳密なロックファイルは使わず、requirements.txtで主要な依存関係を管理するに留めています。

その理由は私がWindows, 複数のLinuxディストリビューション(WSL含む), macOS, そしてFreeBSDといった多様なプラットフォームで開発を行っていて、過去の経験上、プラットフォームをまたいで厳密なバージョンロックを維持しようとすると、かえって問題が発生することが少なくありませんでした。特定のOSでしか利用できないバイナリ依存関係などが原因で、ロックファイルが他のOSでは使えない、といった事態に陥りがちです。

それに私の重要なサービスはすべてコンテナイメージとしてデプロイしています。uv.lock がないことで、ビルドのたびにパッケージバージョンが完全に一致するわけではありませんが、何か問題が起きても、過去のコンテナイメージを追跡すれば、原因究明は十分に可能です。私にとっては、クロスプラットフォーム開発の柔軟性を損なうデメリットの方が、ビルドの完全な再現性がもたらすメリットを上回ると判断しています。

もし必要がある重大なサービスの場合、 uv.lock使うか、 uv compile か pip-dep-tree でテキストのロックファイル作るかで、バージョンを確定させるやり方はあります。

uvには他にも多くのサブコマンドがありますが、正直なところ、他のコマンドは既存のツールで十分だと感じています。この2つの機能（uv pythonとuv pip install）だけでも、uvを導入する価値は十二分にあります。（もし私が見逃している宝物のような機能があれば、ぜひ教えてください）

Discussion