---
title: "uvとは？Pythonの環境構築・パッケージ管理・バージョン管理の使い方を徹底解説"
url: "https://www.issoh.co.jp/tech/details/4384/"
published: 2024-12-03
updated: 2026-10-13
categories: ["Python"]
publisher: "株式会社一創"
---

# 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の役割と基本概要を詳しく解説](/tech/details/9572/)」も参考になります。

なお、現在Astralが保守しているRyeも似た目的のツールですが、機能の多くがuvに引き継がれ、公式にもuvへの移行が案内されています。Rye自体の概要は「[Ryeの概要とPythonプロジェクト管理における重要性](/tech/details/3771/)」で確認できます。これから新しく環境を整えるなら、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を用意する必要がありません。pyenv側の仕組みと導入手順は[pyenvでPythonのバージョンを切り替える手順](https://www.issoh.co.jp/tech/details/17513/)で個別に扱っています。

```
# 特定バージョンをインストール
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の概要と新機能についての全体像](/tech/details/4042/)」や「[Python 3.14で追加された新機能の概要とアップデート全体像](/tech/details/9409/)」、uv 0.13.0で既定の版になった3.15については「[Python 3.15の新機能と3.14から上げる手順](https://www.issoh.co.jp/tech/details/18312/)」もあわせて確認してください。

## 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         | 確定バージョンの記録    |
| .python-version | 使用Pythonバージョン |
| .venv/          | 仮想環境          |

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

```
# 依存を追加（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は複数ツールの役割を兼ねるため、従来ツールとの対応関係を押さえると理解しやすくなります。下表は主な担当範囲の比較です。

| ツール    | パッケージ管理 | 仮想環境 | Python本体管理 | ロックファイル |
| ------ | ------- | ---- | ---------- | ------- |
| uv     | ○       | ○    | ○          | ○       |
| pip    | ○       | ×    | ×          | △       |
| Poetry | ○       | ○    | ×          | ○       |
| pyenv  | ×       | ×    | ○          | ×       |
| conda  | ○       | ○    | ○          | △       |

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

## よくあるエラーと対処

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プロジェクト管理における重要性](/tech/details/3771/)
- [Cargoとは何か？Rust公式のパッケージ管理・ビルドツールCargoの役割と基本概要を詳しく解説](/tech/details/9572/)
- [condaとpipの違いから学ぶAnacondaでのパッケージ管理方法](/tech/details/7775/)
- [Python 3.13の概要と新機能についての全体像](/tech/details/4042/)
- [Python 3.14で追加された新機能の概要とアップデート全体像](/tech/details/9409/)

---

出典: [uvとは？Pythonの環境構築・パッケージ管理・バージョン管理の使い方を徹底解説](<https://www.issoh.co.jp/tech/details/4384/>)（株式会社一創）