Python パッケージ管理 uv

uv とは何か

Astral（ruff の開発元）が作った Python のパッケージ管理ツール。Rust 実装で、とにかく速いです。インストールって結構時間かかったりするからね。

「venv + pip + pyenv をまとめて一本化する」ことを目指しているツールで、だいぶ普及してきてるっぽいです。

---

インストール

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

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Homebrew
brew install uv

# pip 経由でも入れられる
pip install uv

---

仮想環境を作る（venv と同じことができる）

venv が遅いから嫌だって言う人向け

uv venv

デフォルトで .venv ディレクトリが作られる。有効化・無効化は venv と同じ。

# Mac / Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

# 無効化
deactivate

有効化したあとのパッケージインストールは uv pip を使います。pip を uv pip に置き換えるだけでだいたいは動くはず。

# pip install requests のかわりに
uv pip install requests

# requirements.txt からインストール
uv pip install -r requirements.txt

# requirements.txt を書き出す
uv pip freeze > requirements.txt

---

Python 自体のバージョン管理（pyenv の代替）

インストール・削除

uv で Python のバージョンをインストール・削除できます。
これはプロジェクトごとというわけではなくて、uvの管理下にいろんなバージョンのpythonを持っておくことができるということです。
そこからプロジェクトごとに使いたいものを使う感じ。

# Python 3.12 をインストール
uv python install 3.12

# インストール済みの Python 一覧
uv python list

# アンインストール
uv python uninstall 3.12

使うバージョンを指定する

インストールしたバージョンを使うには 2 つの方法があります。

その場限りで指定する（--python オプション）

uv venv --python 3.12

指定したバージョンがまだ入っていなければ uv が自動でダウンロードしてくれます。

すでに .venv がある状態で実行すると上書きして作り直してくれます。ただしパッケージは引き継がれないので、上書き後に入れ直さないといけないですね。

# requirements.txt がある場合
uv pip install -r requirements.txt

# pyproject.toml で管理している場合
uv sync

ディレクトリに固定する（uv python pin）

uv python pin 3.12

このコマンドを打つと.python-version ファイルが作られ、以降そのディレクトリでは --python を指定しなくても自動で 3.12 が使われるようになります。git で共有すればチーム全員が同じバージョンを使える感じですね。

---

プロジェクト管理（poetry に近い）

uv はプロジェクト単位の依存管理もできます。こっちがメイン機能なんでしょうね。pyproject.toml で管理します。

# プロジェクトを初期化
uv init my-project

実行すると以下のファイルが勝手に作られます。.git も一緒に作られるので git init やるまえにやりましょ。
この時点では .venv は作られないです。uv sync や uv add を初めて実行したタイミングで作られます。

my-project/
├── .git/
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
└── hello.py

# 依存を追加
uv add requests

# 依存を削除
uv remove requests

# ロックファイルを元に依存をインストール
uv sync

uv add すると pyproject.toml と uv.lock が自動で更新されます。
pyproject.tomlを手動で編集することもたまにあると思うんですが、そのときはsyncを忘れないようお気をつけくださいな。

Python バージョンを指定したい場合

init 時に指定できます。もしくはあとから uv python pin で変更できます。

# init 時に指定
uv init --python 3.12 my-project

# あとから変更
uv python pin 3.12

どちらも .python-version が更新されるので、git で共有すればチーム全員が同じバージョンを使えるようになります。

uv venv --python 3.12 でも .venv は指定バージョンで作られるんですが、.python-version は更新されないっぽいです。一応 uv python pin を使う方がいいっすね。

---

よくある流れ

venv, pip の代替として使う（シンプルな使い方）

# 仮想環境を作って有効化
uv venv
source .venv/bin/activate

# パッケージをインストール
uv pip install requests

# 依存を記録
uv pip freeze > requirements.txt

プロジェクト管理として使う（poetry に近い使い方）

# プロジェクトを初期化
uv init my-project
cd my-project

# 依存を追加
uv add requests

# 環境を構築
uv sync

# 仮想環境有効化のコマンドをいちいちうたずともそのまま実行できる
uv run python main.py
uv run pytest

---

venv / poetry との比較

venv は手軽です。手っ取り早いです。uv は全部できるんでこれだけ覚えとけば困りはしないと思います。

---

あとがき

uv 覚えとけばいいんだろうなと思ってます。一時期 rye って名前じゃなかったかな。経緯がわからないけどいつの間にか uv になってた。
init系のコマンドっていきなり色々作成されるから毎回ちょっと焦るっす。