Pythonの環境づくりを「uv」1つにまとめる　インストールから実行までの手順

Pythonで開発を始めるとき、Python本体の入手、仮想環境づくり、ライブラリの導入と、別々の道具を使い分けるのが当たり前だった。米Astralが開発する「uv」は、これらを1つのコマンドにまとめた道具だ。Rustで書かれていて動作が速く、最近はuvを前提にした手順書も増えている。この記事では、uvを入れてから、プロジェクトを作って動かすまでを、実際のコマンドに沿って紹介する。

インストールは1行

macOSとLinuxでは、公式のインストーラーを次のコマンドで実行する。

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

Windowsでは、PowerShellから次のコマンドを実行する。

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

uvの本体は、macOSとLinuxでは ~/.local/bin/uv に、Windowsでは $HOME\.local\bin\uv.exe に置かれる。後から新しい版に上げるときは、uv self update を実行すればよい。

Python本体もuvで入れる

uvは、Python本体の入手も受け持つ。OSに入っているPythonとは別に、プロジェクトごとに必要な版を用意できる。

uv python install 3.12
uv python list

1行目で3.12を入れ、2行目で、入れた版と入れられる版の一覧を見る。複数の版を一度に入れることもできる。

プロジェクトを作る

新しいプロジェクトは uv init で作る。

uv init hello-world
cd hello-world

フォルダーの中には、設定を書く pyproject.toml、使うPythonの版を記す .python-version、最初のプログラムなどが作られる。

ライブラリを足すときは uv add を使う。

uv add requests
uv add 'requests==2.31.0'

uv add を実行すると、pyproject.toml に使うライブラリが書き込まれ、正確な版を記録した uv.lock が更新される。ライブラリは、プロジェクト専用の仮想環境 .venv に入る。uv.lock はバージョン管理に含め、手で書き換えないのが決まりだ。

動かす

プログラムは uv run で実行する。

uv run example.py
uv run -- flask run -p 3000

uv run は、実行の前に .venv が pyproject.toml と uv.lock に合っているかを確かめ、ずれていれば直してから動かす。仮想環境を自分で有効にする手間が要らない。仮想環境を有効にして使いたいときは、uv sync で .venv をそろえてから、macOSとLinuxなら source .venv/bin/activate を実行する。

既存のプロジェクトから移る

requirements.txt で依存を管理してきたプロジェクトは、次のコマンドで取り込める。

uv add -r requirements.txt

チームで使うときは、pyproject.toml と uv.lock をリポジトリに入れておけば、ほかの人は uv sync を実行するだけで同じ環境をそろえられる。

どこから始めるか

uvは、pipや仮想環境の作り方を覚え直さなくても、uv init、uv add、uv run の3つでひととおり使える。まずは手元の小さなスクリプトを1つ、uv run で動かしてみるのが入り口としてよい。

参考

• uv: Installing uv
• uv: Working on projects
• uv: Installing Python