uvのインストールと使い方（pyenvよりも高速）－ Python環境構築

uvは、Python開発に必要なツールを（Python自体のインストール、パッケージ管理、仮想環境）をすべて一つにまとめ、高速にしたツールです。

従来はpyenvを用いてPythonのバージョン管理、pipでパッケージ管理、venvで仮想環境というように異なるものを使用していましたが、uvではそれらが全て１つになっています。

pipと比べて、パッケージのインストールが10倍から100倍速くなることもあります。uv自体はPythonではなくRustで作られているため、Pythonがインストールされていない環境でも、専用の実行ファイルを1つ入れるだけで動き出します。

本記事では、uvのインストール方法と使い方を説明します。

従来環境との比較表

項目	従来のツール	uv
言語管理	pyenv	uv python
ライブラリ管理	pip / poetry	uv add / remove
仮想環境	venv	不要（自動管理）
実行	python main.py	uv run main.py

uvは独立して動くため既存のpyenvやpoetryと共存可能です。

インストール方法

Windowsの場合

PowerShellを開いて、以下のコマンドを実行します。

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

Linux/Macの場合

ターミナルを開いて、以下のコマンドを実行します。

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

Homebrewを使いたい場合、以下のコマンドでもインストール可能です。

brew install uv

インストールの確認方法

インストールが終わったら、一度ターミナルを再起動してから、以下のコマンドを打ちます。

uv --version

これでバージョン番号が表示されていれば成功です。

使い方

この記事はuv v0.10.2を使用して動作確認しております。

Python をインストールする方法

uvを入れたら、まずはPythonそのものをインストールしてみましょう。pyenvを使っていた時よりも圧倒的に速いはずです。

特定のバージョンを入れる場合（例：3.12）

uv python install 3.12

どのバージョンのPythonがインストールされているか（および、インストール可能か）を一覧でみるには、次のコマンドを使用します。

uv python list

パスが表示されているものがインストール済みのPythonです。インストールされたものだけ表示したい場合は--only-installedを付けます。

Pythonをアンインストールする方法

インストールしたPythonを削除するには以下のコマンドを使用します。

uv python uninstall 3.12

Python のバージョン切り替え

特定のプロジェクトディレクトリで「このプロジェクトはPython 3.12を使う」と決めたい場合、以下のコマンドを打ちます。

uv python pin 3.12

このようにすると、そのディレクトリに.python-versionというファイルが作られます。そのディレクトリにいる間、uv runなどのコマンドは自動的に3.12を使います。この設定はサブディレクトリにも適用されます。

現在のディレクトリでどのPythonが動くかの確認をしたい場合は、以下のコマンドを打ちます。

uv run python --version

現在のディレクトリで動くPythonの場所が知りたい場合は、以下のコマンドを打ちます。

uv python find

通常はuv python pinは使いません。仮想環境構築でuv initを使う際にpythonのバージョンを指定する方が安定に運用できます。uv python pinは例えば、pythonのバージョンを指定せずに空の.venvを作成した場合、pythonのバージョンを後から指定するのに使います。

仮想環境の作り方

プロジェクトとして作成する場合（おすすめの方法）

まず、プロジェクトを初期化します。

uv init my-app

uv init --python 3.12 my-app   (Pythonのバージョンを指定したい場合）

my-appは作成するプロジェクトフォルダの名前で好きなものに変えます。プロジェクトフォルダが作られるので、そのフォルダの中でライブラリをインストールします。例えば、numpyをインストールしたい場合のコマンドを記述します。

uv add numpy

ライブラリをインストールした時点で仮想環境が自動的に作成されます。ユーザーが仮想環境を有効化する必要はありません。uvが実行する際に自動的にそのディレクトリにある仮想環境を有効化します（uv addはハードリンクが使えない環境では警告がでます。正しく動作していますので、そのままで問題ありません。詳細は後述の「ライブラリのインストール」の注意点をご確認ください）。

.venvはuv initを実行した直後には作成されず、uv addやuv runをした瞬間に自動的に作成されます。

従来のvenvを使う方法（python -m venvの代わり）

特定のディレクトリに.venvフォルダを作りたいだけの場合は、以下のコマンドを使います。

uv venv

特定のバージョンを指定したい場合は、以下のようにします。

uv venv --python 3.12

ユーザーが仮想環境を有効化する必要はありません。uvが実行する際に自動的にそのディレクトリにある仮想環境を有効化します。

従来通り .venv内のactivateを実行することで有効化、deactivateを実行することで無効化することもできます。

何らかの理由で仮想環境を作り直したい場合は.venvフォルダを削除してから、uv venvを使用すれば仮想環境を最初から再構成できます。この場合pyproject.toml と uv.lock はそのままで大丈夫です。uv sync を実行すれば、uv が新しいPythonバージョンとライブラリの相性を自動で計算し、必要があればライブラリを適切なバージョンへ更新してくれます。万が一、ライブラリが古すぎて新しいPythonで動かない場合は uv がエラーで教えてくれるので、その時だけ対応を考えます。

Python を実行する

uvでPythonを実行するには、以下のコマンドを使用します。

uv run main.py

自動的に仮想環境を読み取り、そのディレクトリで定義された依存関係を使って実行してくれます。

特定のライブラリを一時的に使ってスクリプトを動かすこともできます。

uv run --with pandas python -c "import pandas; print('Hello Pandas')"

ruffやblackといったツールを、インストールせずに最新版で実行できます。

uvx ruff check .

ruff checkコマンドを打つと、ruffというツールがあなたのコードを高速に読み取り、「未使用の変数がないか」「書き方に間違いがないか」をチェックしてくれます。.はチェック対象で、今のフォルダ全部という意味があります。

ライブラリのインストール

すでに仮想環境で触れたように、ライブラリは次のコマンドでインストールします。

uv add numpy

numpyはライブラリ名で、インストールしたいライブラリの名前に変更します。特定のバージョンを入れたい場合は、以下のような方法があります。

uv add pandas==2.2.2
uv add pandas>=2.0.0
uv add "pandas>=2.0.0,<3.0.0"

ライブラリ情報をファイルに書き出すには、以下のようにします。

uv export --format requirements-txt > requirements.txt

pipやdockerなど他のツールから使用する場合に便利です。uvでライブラリを一括でインストールするには以下のようにします。

uv add -r requirements.txt

以下のwarningはハードリンクが使用できなかったので、普通のコピーで動かしましたという警告です。ハードリンクは同じディスク（同じパーティション）内でしか使えないので、その場合はコピーモードが使われますが問題ありません。

warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
If the cache and target directories are on different filesystems, hardlinking may not be supported.
If this is intentional, set export UV_LINK_MODE=copy or use --link-mode=copy to suppress this warning.

もし、どうしても気になるのであれば、windowsであれば以下を実行します。
$env:UV_LINK_MODE="copy"
Linux / Macであれば、.bashrcや.zshrcに以下を記述すれば、発生しなくなります。
export UV_LINK_MODE=copy
ただし、ハードリンクが使える環境でもコピーモードが使われてしまいます。

インストールしたライブラリの一覧をみる

シンプルに一覧を見る場合には次のコマンドを打ちます。pip listと同じ感覚で表示します。

uv pip list

依存関係のつながりを見る場合には以下のコマンドを打ちます。

uv tree

ライブラリの削除

特定のライブラリをプロジェクトから消したい場合は、以下のコマンドを打ちます。

uv remove numpy

numpyは削除したいライブラリの名前に書き換えます。このコマンドを実行すると、仮想環境（.venv）とプロジェクトの台帳（pyproject.toml）から名前が消え、設計図（uv.lock）も最新の状態に更新されます。

手動でpyproject.tomlからライブラリを消した場合は、以下のコマンドを打つと現在の設定ファイルに合わせて環境をクリーンな状態にできます。

uv sync

特定のバージョンで実行する

特定のスクリプトを別のバージョンで試したいときは、フラグを付けます。

uv run --python 3.12 main.py

もし、そのバージョンのPythonがインストールされていなければ、uvがその場でダウンロードして実行してくれます。ただし、仮想環境を構築している場合には、Python自体やライブラリに互換性がないときにはエラーが発生します。このため、仮想環境作成時に使用するPythonを定義するのがおすすめです。

環境を復元する

プロジェクトの台帳（pyproject.toml）に書かれたライブラリリストから仮想環境を構築できます。ロックファイル（uv.lock）があれば、より環境の再現が厳密になります。例えば、gitからクローンしたときに環境構築に使えます。

uv sync

このコマンドを実行すると、pyproject.tomlに書かれたライブラリのリストを確認します。そして、uv.lockがあれば、そこに記録された厳密なバージョンを確認します（ない場合は新しく作ります）。そして、足りないライブラリを一気にダウンロードし、.venv（仮想環境）を作成して中身を整えます。

uv syncを実施しなくても、git cloneした後にuv runを実行すると、裏で自動的にuv syncを実行してからプログラムを動かしてくれます。

gitに保存するファイル

uv initをすると自動で.gitignoreが作られ、重いライブラリが入る.venvフォルダは無視されるようになっています。代わりに、pyproject.tomlとuv.lockの2つを必ずGitに保存するようにします。これらさえあれば、他の人がuv syncと打つだけで、まったく同じ環境を再現できます。

まとめ

本記事のまとめとして、主要なコマンド一覧を整理しました。ご参考になれば幸いです。

やりたいこと	コマンド
Pythonの導入	uv python install 3.12
プロジェクト開始	uv init --python 3.12 my-app
ライブラリ追加	uv add pandas
プログラム実行	uv run main.py
環境の同期（復元）	uv sync
依存関係の確認	uv tree
ライブラリリストの作成	uv export --format requirements-txt > requirements.txt
ライブラリリストの読み込み	uv add -r requirements.txt
uvの更新	uv self update