はじめに
uvは、Ruffの開発元であるAstral社が開発しているRust製のPythonパッケージ・プロジェクト管理ツールです。pip・venv・pyenvなどの役割を1つのツールで担います。
本記事では、pipとの違いと、日常的に使う機能に絞って使い方を整理します。
動作確認環境:uv 0.12.18 / macOS(Apple Silicon)
pipとの違い
| pip(+venv / pyenv) | uv | |
|---|---|---|
| 速度 | 標準的 | 10〜100倍高速(公式値) |
| 仮想環境 |
venv で作成し、activateが必要 |
自動で作成。activate不要 |
| 依存関係の記録 |
pip freeze で手動 |
pyproject.toml / uv.lock に自動記録 |
| 環境の再現 |
requirements.txt(間接依存は固定されにくい) |
uv.lock で間接依存まで固定 |
| Pythonのバージョン管理 | pyenvなど別ツール |
uv python で管理 |
1. 高速
依存関係の解決・ダウンロード・インストールをRustで並列処理します。また、グローバルキャッシュにより、一度ダウンロードしたパッケージは別プロジェクトでも再利用されます。numpy・pandas・torchなど大きなライブラリを繰り返しインストールする環境ほど差が出ます。
2. 1つのツールで完結
従来は目的ごとにツールを組み合わせる必要がありました。
| 用途 | 従来 | uv |
|---|---|---|
| パッケージのインストール | pip |
uv add |
| 仮想環境の作成 |
venv / virtualenv
|
自動 |
| 依存関係の固定 |
pip freeze / pip-tools
|
自動(uv.lock) |
| Python本体の管理 | pyenv |
uv python |
3. 環境の再現性
requirements.txt は手動管理のため、記載漏れや間接依存のバージョンずれが起きがちでした。
uvは2つのファイルを自動で管理します。
-
pyproject.toml:直接追加したパッケージ -
uv.lock:間接依存を含む、解決済みの正確なバージョン
別のPCやチームメンバーの環境でも、uv sync で同一の環境を再現できます。
4. 仮想環境の操作が不要
pipでは「venv作成 → activate → pip install」の手順が必要で、activateを忘れてグローバル環境にインストールしてしまうこともありました。
uvでは uv add や uv run の実行時に、プロジェクトの .venv が自動で作成・使用されます。
インストール
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Homebrew
brew install uv
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
バージョンが表示されればインストール完了です。
uv --version
基本コマンド
日常的に使うのは次の5つです。
| コマンド | 内容 |
|---|---|
uv init |
プロジェクトを作成 |
uv add |
パッケージを追加 |
uv remove |
パッケージを削除 |
uv run |
プロジェクトの環境でコマンドを実行 |
uv sync |
uv.lock の通りに環境を揃える |
uv init:プロジェクトを作成
uv init --no-package my-app
cd my-app
my-app/
├── .git/ # Gitリポジトリも初期化される
├── .gitignore
├── .python-version # 使用するPythonのバージョン
├── README.md
├── main.py # サンプルコード
└── pyproject.toml # プロジェクト設定・依存パッケージ
既存のディレクトリでは、そのディレクトリ内で uv init --no-package を実行します。
--no-package について
uv 0.12時点では、uv init のデフォルトはパッケージ構成(--package)です。src/my_app/__init__.py と [build-system] が生成され、uv run my-app で実行する形になります。
uv init(デフォルト) |
uv init --no-package |
|
|---|---|---|
| 構成 | src/my_app/__init__.py |
main.py(フラット) |
| 実行方法 | uv run my-app |
uv run main.py |
| 用途 | 配布・インポートするライブラリやCLI | スクリプトとして動かすアプリケーション |
本記事では、スクリプトを直接実行するシンプルな --no-package 構成で説明します。
[project]
name = "my-app"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []
requires-python には、作成時に使われたPythonのバージョンが入ります(環境により異なります)。dependencies が requirements.txt に相当します。uv add / uv remove が自動で更新するため、手で編集する必要はありません。
uv add:パッケージを追加
uv add requests
pip install requests に相当しますが、次の処理がまとめて行われます。
-
.venvが無ければ作成 -
.venvにパッケージをインストール -
pyproject.tomlのdependenciesに追記 - 解決したバージョンを
uv.lockに記録
実行後の pyproject.toml:
dependencies = [
"requests>=2.34.2",
]
pipではインストール後に pip freeze > requirements.txt を別途実行する必要がありました。uvはインストールと記録が同時に行われるため、記録漏れが起きません。
バージョン指定
uv add "pandas>=2.0" # 2.0以上
uv add "numpy==1.26.4" # 固定
> や = はシェルで特別な意味を持つため、引用符で囲みます。
複数指定
uv add numpy pandas matplotlib
開発用パッケージ
テストやフォーマッタなど、実行時には不要で開発時のみ使うパッケージは --dev を付けます。
uv add --dev pytest
pyproject.toml の [dependency-groups] の dev に、通常の依存とは分けて記録されます。
uv remove:パッケージを削除
uv remove requests
.venv からアンインストールされ、pyproject.toml と uv.lock からも削除されます。pipのように、アンインストール後も requirements.txt に記載が残ることはありません。
uv run:コマンドを実行
uv run main.py
python main.py の代わりに使います。プロジェクトの .venv 内のPythonで実行されるため、activateは不要です。
# pip
source .venv/bin/activate
python main.py
# uv
uv run main.py
実行前に pyproject.toml と環境の整合性を確認し、不足しているパッケージがあれば自動でインストールします。
Python以外のコマンドも .venv 内で実行できます。
uv run pytest # .venvのpytestを実行
uv run python # .venvのPythonで対話モードを起動
VS Codeなどのエディタでは、インタープリタにプロジェクトの .venv を指定すると、補完やエラー表示が正しく機能します。
uv sync:環境を揃える
uv sync
uv.lock に記録されたバージョンで .venv を構築します。主な用途は次の通りです。
- リポジトリをクローンした直後
- 別のPCで同じ環境を作るとき
- 他の開発者が追加・変更した依存関係を反映するとき
pipでの「venv作成 → activate → pip install -r requirements.txt」が1コマンドで済みます。ロックされたバージョンがそのまま入るため、環境差異による「手元では動く」問題を防げます。
pyproject.toml・uv.lock・.python-version はGit管理対象にします。.venv は uv sync でいつでも再作成できるためコミット不要です(uv init が生成する .gitignore で除外済み)。
使用例
Webページを取得する簡単なプログラムを作成します。
uv init --no-package hello-uv
cd hello-uv
uv add requests
import requests
def main():
res = requests.get("https://example.com")
print(res.status_code)
if __name__ == "__main__":
main()
uv run main.py
# => 200
venvの作成、activate、requirements.txt の更新はいずれも行っていません。
別の環境では次の手順で再現できます。
git clone <リポジトリのURL>
cd hello-uv
uv sync
uv run main.py
Pythonのバージョン管理
「ライブラリが3.11までしか対応していない」「新規プロジェクトは3.13で作りたい」など、プロジェクトごとにPythonのバージョンを使い分ける場面は多くあります。従来はpyenvなどの別ツールが必要でしたが、uvはPython本体のインストールと切り替えも行えます。
一覧を確認
uv python list # 利用可能なバージョンとインストール済みのバージョン
uv python list --only-installed # インストール済みのみ
uvでインストールしたものに加え、Homebrewや公式インストーラで導入済みのPythonも検出・利用されます。
インストール
uv python install 3.12 # 3.12系の最新
uv python install 3.11 3.12 3.13 # 複数
uv python install 3.12.4 # パッチバージョン指定
uv専用のディレクトリに配置されるため、システムのPythonには影響しません。複数のバージョンは並存し、新しいバージョンを入れても既存のバージョンが消えることはありません。
プロジェクト作成時に指定
uv init --no-package my-app --python 3.11
.python-version が 3.11、pyproject.toml の requires-python が >=3.11 になります。
requires-python は、そのプロジェクトで使えるバージョンの下限になります。複数バージョンを切り替えて使う予定がある場合は、使う中で最も古いバージョンを指定して作成します。
バージョンを切り替える
インストール済みの複数バージョンは、用途に応じて次の3つの方法で切り替えます。
| 切り替えの範囲 | コマンド | pyenvでの相当 |
|---|---|---|
| プロジェクト単位 | uv python pin <バージョン> |
pyenv local |
| プロジェクト外のデフォルト | uv python pin --global <バージョン> |
pyenv global |
| 1回の実行のみ | uv run --python <バージョン> ... |
pyenv shell |
プロジェクト単位で切り替える
# 3.11と3.13をインストール(並存する)
uv python install 3.11 3.13
# 3.11以上に対応するプロジェクトを作成
uv init --no-package my-app --python 3.11
cd my-app
# 3.13に切り替え
uv python pin 3.13
uv run python --version
# => Python 3.13.x
# 3.11に切り替え
uv python pin 3.11
uv run python --version
# => Python 3.11.x
uv python pin は、プロジェクトで使うバージョンを .python-version に設定します。切り替えるのは「どのバージョンを使うか」の指定だけで、インストール済みのPythonはそのまま残ります。
切り替え後の uv run / uv sync 実行時に、uvが .venv とのバージョン不一致を検出し、.venv を指定バージョンで再作成してパッケージを再インストールします。
pyenvでは「Pythonの切り替え → 仮想環境の再作成 → パッケージの再インストール」を手動で行う必要がありましたが、uvではすべて自動です。
プロジェクト外のデフォルトを切り替える
uv python pin --global 3.12
.python-version が無いディレクトリで、uvが使うデフォルトのバージョンを設定します。設定は ~/.config/uv/.python-version に保存され、uv python pin --global --rm で解除できます。
1回の実行だけ切り替える
uv run --python 3.13 python --version
別バージョンでの動作を一度だけ確認したい場合に使います。.python-version は変更されないため、プロジェクトの設定はそのままです。なお、このとき .venv は指定バージョンで再作成され、次に --python なしで uv run を実行すると .python-version のバージョンで再作成されます。
requires-python の範囲外のバージョンには切り替えられません。たとえば requires-python = ">=3.12" のプロジェクトで uv python pin 3.11 や uv run --python 3.11 を実行するとエラーになります。
error: The requested Python version `3.11` is incompatible with the project `requires-python` value of `>=3.12`.
古いバージョンに切り替える場合は、先に pyproject.toml の requires-python を ">=3.11" などに変更してください。
.python-version と requires-python
| 設定 | 場所 | 意味 |
|---|---|---|
.python-version |
.python-version |
開発環境で実際に使うバージョン(例:3.12) |
requires-python |
pyproject.toml |
プロジェクトが対応するバージョンの範囲(例:>=3.12) |
バージョンの切り替えは、通常 .python-version を uv python pin で設定すれば十分です。
自動ダウンロード
指定したバージョンがインストールされていない場合、uv init --python、uv python pin 後の uv run / uv sync などの実行時に自動でダウンロードされます。そのため、通常は uv python install を明示的に実行しなくても、バージョンを指定するだけで動作します。
削除
uv python uninstall 3.11
削除対象はuvでインストールしたPythonのみです。Homebrewなどで導入したPythonは削除されません。
pipとのコマンド対応
| 操作 | pip / pyenv | uv |
|---|---|---|
| 仮想環境の作成 | python -m venv .venv |
不要(自動) |
| 仮想環境の有効化 | source .venv/bin/activate |
不要 |
| パッケージの追加 | pip install requests |
uv add requests |
| パッケージの削除 | pip uninstall requests |
uv remove requests |
| 依存関係の記録 | pip freeze > requirements.txt |
不要(自動) |
| 環境の再現 | pip install -r requirements.txt |
uv sync |
| 実行 | python main.py |
uv run main.py |
| Pythonのバージョン切り替え |
pyenv install 3.12 → pyenv local 3.12 → venv再作成 |
uv python pin 3.12 |
従来手作業で行っていた操作の多くが、uvでは不要または自動化されています。
まとめ
- uvはpip・venv・pyenvの役割を1つにまとめた、Rust製の高速なPython管理ツール
- 基本操作は
uv init・uv add・uv remove・uv run・uv syncの5つ - 仮想環境の作成・activate・依存関係の記録は自動で行われる
-
uv.lockとuv syncにより、どの環境でも同一の構成を再現できる - Pythonのバージョンは
uv python pinでプロジェクトごとに切り替えられる