uv 入門チュートリアル -- Python パッケージ管理・環境管理ツール

Python 開発において、パッケージ管理と環境分離は、すべての開発者が直面する問題です。pip の遅さ、virtualenv の煩雑さ、conda の肥大化など、uvこれらにより、開発者たちはより効率的なソリューションを求めています。

uv とは何か？

uv は Astral 社が開発した、Rust で書かれた Python パッケージマネージャー兼環境マネージャーです。主な目標は、既存のツールより 10〜100 倍高速なパフォーマンスを提供しつつ、シンプルで直感的なユーザーエクスペリエンスを維持することです。

uv は pip、virtualenv、pip-tools、pyenv などのツールを置き換え、依存関係の管理、仮想環境の作成、Python バージョン管理などをワンストップで提供します。

uv の利点

• 非常に高速：Rust で書かれているため、uv のパフォーマンスは pip や他のパッケージ管理ツールをはるかに上回り、依存関係のインストール速度は 10〜100 倍向上します。
• 機能の統合：依存関係の解決、パッケージのインストール、環境管理、Python バージョン管理を一体化しており、複数のツールをインストールして学ぶ必要がありません。
• 再現性のあるビルド：uv はuv.lockファイルを生成し、どの環境でも完全に同じ依存関係バージョンをインストールできるようにして、「自分のマシンでは動くのに」という問題を防ぎます。
• 既存ツールとの互換性：uv はrequirements.txtとpyproject.tomlを処理でき、既存のワークフロー内の pip をシームレスに置き換えることができます。

---

uv のインストール

macOS でのインストール

Homebrew でのインストールを推奨します：

brew install uv

または公式インストールスクリプトを使用：

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

Linux でのインストール

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

Windows でのインストール

Winget を使用：

winget install uv

または公式インストールスクリプト（PowerShell）を使用：

irm https://astral.sh/uv/install.ps1 | iex

インストール完了後、成功したかどうかを確認します：

uv --version

出力が以下のようになれば、インストール成功です：

uv 0.8.14 (Homebrew 2025-08-28)

---

1、Python バージョンの管理

uv には Python バージョン管理機能が組み込まれており、pyenv などのツールを追加でインストールする必要はありません。

利用可能な Python バージョンの確認：

uv python list

出力結果は次のようになります：

cpython-3.14.0rc2-macos-aarch64-none                 <download available>
cpython-3.13.7-macos-aarch64-none                    <download available>
cpython-3.12.11-macos-aarch64-none                   <download available>
cpython-3.11.13-macos-aarch64-none                   <download available>
cpython-3.10.18-macos-aarch64-none                   <download available>
cpython-3.9.6-macos-aarch64-none                     /usr/bin/python3
pypy-3.11.13-macos-aarch64-none                      <download available>

特定のバージョンの Python をインストール：

# 安装最新的 Python 3.12
uv python install 3.12

# 安装特定版本
uv python install 3.11.6

# 安装 PyPy 版本
uv python install pypy3.10

グローバルのデフォルト Python バージョンを設定：

uv python default 3.12

現在のプロジェクトに Python バージョンを固定（.python-versionファイルが作成されます）：

uv python pin 3.12

このコマンドを実行すると、現在のプロジェクトに .python-version が生成され、開くとバージョン番号が表示されます：

3.12

---

2、仮想環境の管理

仮想環境の作成：

# 在当前目录创建名为 .venv 的虚拟环境（使用系统默认 Python）
uv venv

# 使用指定 Python 版本创建虚拟环境
uv venv --python 3.12

仮想環境のアクティブ化：

# macOS / Linux
source .venv/bin/activate

# Windows（PowerShell）
.venv\Scripts\activate

仮想環境の終了：

deactivate

日常開発では、uv runを使用してスクリプトを直接実行でき、仮想環境を手動でアクティブ化する必要はありません。

---

3、パッケージ管理（pip 互換モード）

uv は pip と完全に互換性のあるコマンドインターフェースを提供しており、既存のワークフロー内の pip コマンドを直接置き換えることができます：

パッケージのインストール：

# 安装最新版本
uv pip install requests

# 安装特定版本
uv pip install requests==2.31.0

# 从 requirements.txt 批量安装
uv pip install -r requirements.txt

パッケージのアップグレード：

uv pip install --upgrade requests

パッケージのアンインストール：

uv pip uninstall requests

インストール済みパッケージの確認：

uv pip list

現在の環境の依存関係を requirements.txt にエクスポート：

uv pip freeze > requirements.txt

---

4、プロジェクト管理（推奨方法）

uv はpyproject.tomlを中心とした最新のプロジェクト管理方法をサポートしており、これは pip モードよりも推奨される使い方で、特にチーム協業や複数環境へのデプロイに適しています。

プロジェクトの初期化

uv init my_project
cd my_project

これにより、以下の基本プロジェクト構造が作成されます：

my_project/
├── pyproject.toml    # 项目配置和依赖声明
├── .python-version   # 固定 Python 版本
├── README.md
└── main.py

依存関係の追加と削除

プロジェクトモードでは、推奨方法はuv addとuv removeを使用して依存関係を管理することです。これらは自動的に更新されますpyproject.tomlとuv.lock：

# 添加生产依赖
uv add requests

# 添加指定版本的依赖
uv add "requests>=2.31.0"

# 添加开发依赖（只在开发环境使用，如测试框架）
uv add --dev pytest ruff

# 移除依赖
uv remove requests

プロジェクトの全依存関係をインストール（uv sync）

プロジェクトをクローンするか、pyproject.tomlを更新した後、次のコマンドを実行すると、すべての依存関係をワンクリックでインストールできます：

uv sync

uv sync の説明：～と同様に、pip install -r requirements.txtこれは～に基づいてpyproject.tomlとuv.lockすべての依存関係をインストールし、環境が他の開発者と完全に一致するようにします。インストールが遅い場合は、pyproject.tomlに国内ミラーソースを設定できます：

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

ロックファイルの生成/更新

uv lock

このコマンドはpyproject.toml内の依存関係を解析し、uv.lockファイルを生成（または更新）します。uv.lockはバージョン管理システムにコミットし、チームの全メンバーが完全に同じ依存関係バージョンを使用することを確実にします。

---

5、スクリプトの実行（uv run）

uv runは uv の中でも非常に実用的なコマンドで、仮想環境を手動でアクティブ化する必要がなくスクリプトやコマンドを直接実行できます。uv は自動的に正しい環境を見つけて使用します：

# 直接运行 Python 脚本
uv run main.py

# 运行项目中的测试
uv run pytest

# 运行任意命令（在虚拟环境的上下文中执行）
uv run python -c "import requests; print(requests.__version__)"

を使用する場合、uv run手動で環境をアクティブ化する場合と比較した利点：誤った Python バージョンを使用することがなく、環境のアクティブ化を忘れてパッケージが見つからないこともありません。特に CI/CD やスクリプト自動化に適しています。

---

uv への移行

他のツールを使用している場合は、以下の方法で uv に移行できます：

pip + virtualenv からの移行：

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 安装原有依赖
uv pip install -r requirements.txt

pip-tools からの移行：

# 编译依赖（替代 pip-compile）
uv pip compile requirements.in -o requirements.txt

# 同步环境（替代 pip-sync）
uv pip sync requirements.txt

poetry または pdm からの移行：

# 直接使用现有的 pyproject.toml
uv sync

その他の拡張