uvとは？Pythonの環境構築・パッケージ管理・バージョン管理の使い方を徹底解説

uvは、Rust言語で書かれた非常に高速なPythonのパッケージ管理・プロジェクト管理ツールです。これまでpip・venv・pyenv・Poetryなど複数のツールに分かれていた「パッケージのインストール」「仮想環境の作成」「Python本体のバージョン管理」「プロジェクトの依存解決」を、uvひとつに統合できるのが最大の特長です。本記事では、uvのインストールから、uv init・uv add・uv run・uv syncによるプロジェクト運用、uv pythonでのバージョン管理、uvxの使い方、そしてpip・Poetry・pyenvとの違いまでを、実際に動くコマンド付きで解説します。

まとめ

uvは、pip・venv・pyenv・Poetryなどの役割を1つにまとめた、Rust製の高速なPython開発ツールです。uv initでプロジェクトを作り、uv add／uv removeで依存を管理し、uv run／uv syncで実行・同期する流れが基本になります。さらにuv pythonでPython本体のバージョン管理まで一元化でき、uvxを使えば仮想環境を作らずにツールを使い捨て実行できます。以下では、インストールから各コマンドの具体的な使い方、pyenv・Poetry・condaとの違いまでを、順を追って解説します。

uvとは何か

uvは、Ruff（高速なPythonリンター）でも知られるAstral社が開発しているツールで、pipの10〜100倍とされる速度でパッケージのインストールや依存関係の解決を行います。高速性の主な理由は、Rust製であること、依存解決を並列で行うこと、一度取得したパッケージをグローバルキャッシュで再利用することの3点です。

設計思想の面では、RustのパッケージマネージャーであるCargoから強い影響を受けています。Cargoがプロジェクトのビルド・依存管理・ロックファイル生成を一手に担うのと同じように、uvもPythonプロジェクトの管理を一元化します。Cargoの役割については「Cargoとは何か？Rust公式のパッケージ管理・ビルドツールCargoの役割と基本概要を詳しく解説」も参考になります。

なお、現在Astralが保守しているRyeも似た目的のツールですが、機能の多くがuvに引き継がれ、公式にもuvへの移行が案内されています。Rye自体の概要は「Ryeの概要とPythonプロジェクト管理における重要性」で確認できます。これから新しく環境を整えるなら、uvを選んでおくのが無難です。

uvのインストール方法（Windows・macOS・Linux）

uvは公式のインストールスクリプトを使うのが最も手軽です。OSごとに次のコマンドを実行します。

macOS・Linux

# 公式スクリプト（推奨）
curl -LsSf https://astral.sh/uv/install.sh | sh

# Homebrew を使う場合（macOS / Linux）
brew install uv

Windows

PowerShellを開き、次のコマンドを実行します。

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

インストール後はシェル（PowerShellやターミナル）を開き直すと、uvコマンドがどのディレクトリからでも使えるようになります。Windowsで「uvが見つからない」場合は、新しいウィンドウを開き直すか、PATHにuvの実行ファイルの場所が含まれているかを確認してください。

pip・pipxからの導入とバージョン確認

すでにPythonが入っている環境では、pipやpipxでも導入できます。インストール済みのバージョン確認や、uv自身の更新は次のとおりです。

# pip / pipx から
pip install uv
pipx install uv

# バージョン確認
uv --version

# uv 自身を最新版に更新（スクリプト導入時）
uv self update

uvでPythonをインストール・バージョン管理する（pyenvの代替）

uvはパッケージだけでなく、Python本体のバージョン管理もできます。これがpyenvを置き換えられる理由です。指定したバージョンをダウンロードして使い分けられるため、別途pyenvを用意する必要がありません。

# 特定バージョンをインストール
uv python install 3.12

# 複数バージョンをまとめてインストール
uv python install 3.12 3.13

# インストール済み・利用可能なバージョンの一覧
uv python list

# 不要になったバージョンを削除
uv python uninstall 3.11

プロジェクトで使うPythonバージョンを固定するにはuv python pinを使います。これがよくある誤解ポイントで、uv python useというコマンドは存在しません。uv python pinを実行すると、カレントディレクトリに.python-versionファイルが作られ、以降のuvコマンドがそのバージョンを使います。

# プロジェクトで使うバージョンを固定（.python-version を生成）
uv python pin 3.12

# 切り替えたいときは別バージョンを pin し直す
uv python pin 3.13

uvでインストールできるバージョンは各リリース時点のものに固定されているため、ごく新しいバージョンを使いたい場合はuv自体の更新が必要なことがあります。新しいPythonの機能差を把握したいときは「Python 3.13の概要と新機能についての全体像」や「Python 3.14で追加された新機能の概要とアップデート全体像」もあわせて確認してください。

uvでプロジェクトを始める（init・add・remove・sync・run・lock）

uvの本領は、プロジェクト単位の管理にあります。uv initでプロジェクトを作成すると、必要なファイルが自動生成されます。

# 新規プロジェクトを作成
uv init myapp
cd myapp

生成される主なファイルは次のとおりです。pyproject.tomlに依存やプロジェクト設定が記録され、.python-versionに使用するPythonバージョン、uv.lockに解決済みの正確なバージョンが記録されます。仮想環境（.venv）とuv.lockは、最初にuv run・uv sync・uv lockのいずれかを実行した時点で作られます。

依存パッケージの追加・削除や、環境の同期、スクリプト実行は次のコマンドで行います。

# 依存を追加（pyproject.toml と uv.lock を自動更新）
uv add requests
uv add "flask>=3.0"

# 依存を削除
uv remove requests

# pyproject.toml / uv.lock に合わせて環境を同期
uv sync

# プロジェクト環境内でスクリプトを実行
uv run main.py
uv run python -V

# 依存を解決して uv.lock を更新
uv lock

uv runは実行前に依存とPythonバージョンの同期を自動で行うため、activateのような有効化操作を手動で行わなくても、常に正しい環境でコマンドが走ります。配布用パッケージを作成する場合はuv buildを使います（uv package buildではありません）。

仮想環境を自動で管理する

uvはプロジェクトごとに仮想環境を自動作成するため、多くの場面でvenvやvirtualenvを手動で作る必要がありません。明示的に仮想環境だけを作りたい場合はuv venvを使います。

# 仮想環境を作成（.venv が作られる）
uv venv

# Pythonバージョンを指定して作成
uv venv --python 3.12

# 有効化（macOS / Linux）
source .venv/bin/activate

# 有効化（Windows）
.venv\Scripts\activate

uvが作る仮想環境は標準のvenvと互換性があるため、既存のツールやエディタの設定をそのまま使えます。

uvxとuvの違い・ツールを使い捨てで実行する

「uvとuvxの違い」は検索でもよく問われます。結論としては、uvxはuv tool runの短縮形で、仮想環境を作らずにツールを一時的に実行するためのコマンドです。プロジェクトの依存に加えたくないが一度だけ使いたいCLIツール（リンターやフォーマッターなど）を、その場で取得して実行できます。

# uvx は uv tool run の短縮形（同じ動作）
uvx ruff check .
uv tool run ruff check .

# よく使うツールを常設インストールしたい場合
uv tool install ruff

使い分けの目安は、uv add＝そのプロジェクトの依存として恒久的に追加、uvx＝プロジェクトを汚さず使い捨てで実行、uv tool install＝どのプロジェクトからでも使える常設コマンドとして導入、です。

pip互換インターフェース（uv pip）

既存のpipワークフローやrequirements.txtをそのまま活かしたい場合は、uv pipインターフェースが使えます。コマンド体系はpipにそろえつつ、速度だけがuvの恩恵を受けられます。

# pip と同じ感覚でインストール
uv pip install requests

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

# requirements.in から requirements.txt を生成（コンパイル）
uv pip compile requirements.in -o requirements.txt

# requirements.txt に環境を厳密同期
uv pip sync requirements.txt

単一ファイルスクリプトとPEP 723

uvは、1ファイルのPythonスクリプトに依存関係を直接書き込むPEP 723（インラインスクリプトメタデータ）に対応しています。これにより、別途requirements.txtやプロジェクトを用意しなくても、スクリプト単体で必要なライブラリを宣言・実行できます。依存はスクリプト先頭のuv add --scriptで追加します。

# スクリプトに依存を追記（PEP 723 ブロックを生成）
uv add --script example.py requests

生成されるブロックは次の形式です。旧来よく誤記される# uv: depという記法ではない点に注意してください。

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
# ]
# ///

import requests
print(requests.get("https://example.com").status_code)

あとはuv runで実行するだけで、uvがブロックを読み取り、一時的な環境に依存をインストールして実行します。再現性を高めたい場合はuv lock --scriptでスクリプト用のロックファイルを作れます。

# スクリプトを実行（一時環境を自動作成）
uv run example.py

# スクリプトのひな形を新規作成
uv init --script example.py

pip・Poetry・pyenv・condaとの違い

uvは複数ツールの役割を兼ねるため、従来ツールとの対応関係を押さえると理解しやすくなります。下表は主な担当範囲の比較です。

pipは単体ではPython本体や仮想環境を管理しないため、従来はpyenvやvenvと組み合わせる必要がありました。uvはこれらを1つにまとめられる点が強みです。データサイエンス寄りでcondaを使ってきた場合の違いは「condaとpipの違いから学ぶAnacondaでのパッケージ管理方法」も参考になります。

よくあるエラーと対処

uvでつまずきやすいポイントと対処を整理します。

uv syncが失敗する／依存がかみ合わない：まずpyproject.tomlのあるプロジェクトディレクトリで実行しているかを確認します。ロックと宣言がずれている場合は、uv lockで解決し直してからuv syncを再実行します。requires-pythonの指定が手元のPythonと矛盾していないかも確認しましょう。

指定したPythonが見つからない：uv python install <バージョン>で対象を入れるか、uv python pinでプロジェクトのバージョンを合わせます。uv python listで利用可能なバージョンを確認できます。

Windowsでuvコマンドが認識されない：インストール直後はシェルを開き直す必要があります。それでも通らない場合はPATH設定を確認してください。

よくある質問（FAQ）

uvとuvxの違いは何ですか？

uvxはuv tool runの短縮形で、仮想環境を作らずにツールを一時的に実行するためのコマンドです。プロジェクトの恒久的な依存として加えたい場合はuv add、その場限りで実行したい場合はuvxを使い分けます。

uvでPythonのバージョンを切り替えるには？

uv python installで目的のバージョンを入れ、uv python pin 3.12のように固定します。.python-versionが更新され、以降のコマンドがそのバージョンを使います。uv python useというコマンドは存在しません。

uvでインストールしたPythonのバージョンを確認するには？

uv python listでインストール済み・利用可能なバージョンを一覧できます。プロジェクトで実際に使われているバージョンはuv run python -Vで確認できます。

pipやpyenvからuvに移行しても大丈夫ですか？

uvはuv pipインターフェースでpip互換のコマンドとrequirements.txtをそのまま扱えるため、段階的に移行できます。Python本体の管理もuvに集約できるため、pyenvを併用していた構成も置き換え可能です。

関連記事

• Ryeの概要とPythonプロジェクト管理における重要性
• Cargoとは何か？Rust公式のパッケージ管理・ビルドツールCargoの役割と基本概要を詳しく解説
• condaとpipの違いから学ぶAnacondaでのパッケージ管理方法
• Python 3.13の概要と新機能についての全体像
• Python 3.14で追加された新機能の概要とアップデート全体像