Pythonのパッケージマネージャ ”uv” 入門
Python開発の新標準ツール「uv」を徹底解説。Rust製で10〜100倍高速、pip・venv・pyenv・pipxの機能を統合し、pyproject.tomlとuv.lockで再現可能な環境を実現。プロジェクト初期化から依存管理、Python本体のバージョン管理まで、uv init・add・runの基本から実践的な使い方までを丁寧に紹介します。
1 はじめに
Python の仮想環境、パッケージ管理まわりのツールは長年「分業制」でした。パッケージは pip、仮想環境は venv や virtualenv、要件固定は pip-tools、Python 本体の切り替えは pyenv、CLI ツールは pipx など、多くのツールを使い分ける必要がありました。
uv は、こうした作業を 1 つに統合した「all-in-one」のツールです。Rust 製でとても高速、かつ pyproject.toml とロックファイル uv.lock を中心に「再現可能な環境」をつくる思想がはじめから入っています。
本記事では、これから uv を使ってみたい人を対象に、uv とは何か・何が強みなのか・どう使うのかについて、詳細に解説します。
2 uv とは
uv は「Python のパッケージ＆プロジェクトマネージャ」です。
プロジェクトの初期化、依存追加・削除、仮想環境の自動作成、ロックファイルによる再現性担保、uvx（＝ uv tool run の別名）での一時ツール実行、さらに Python 本体のインストール・固定まで、たった一つのツールで面倒を見ます。
uv の強み
圧倒的な高速性
- Rust 製で、pip や Poetry と比較して 10〜100 倍高速
- 並列ダウンロード、グローバルキャッシュ、最適化されたメタデータ処理による効率化
- 参照：https://github.com/astral-sh/uv
pip 互換のインターフェース
uv pip installなど pip 互換のコマンドを提供- pip で構築された既存ワークフローからでも段階的に移行可能
再現可能な環境
uv.lockによって、OS や Python バージョンの違いをまたいだ同一解決を実現- チームメンバー全員が同じ環境で開発できる
統合された機能
- pip、pip-tools、pipx、poetry、pyenv、virtualenv などの機能を 1 つのツールで提供
インストール手順
macOS / Linux / Windows ともに 公式のインストーラが用意されています。
macOSであれば、Homebrew でも入ります。
macOS / Linux
# 公式インストーラ
curl -LsSf <https://astral.sh/uv/install.sh> | sh
# Homebrew でも可（macOS）
brew install uv
# バージョン確認
uv self version
Windows
powershell -ExecutionPolicy ByPass -c "irm <https://astral.sh/uv/install.ps1> | iex"3 uv の使い方ガイド
1) プロジェクトを作る
mkdir myapp && cd myapp
uv init
uv init はプロジェクトの雛形を作ります。実行すると、以下のファイルが自動で作成されます。
pyproject.toml：プロジェクトの設定と依存関係を記述.python-version：プロジェクトの既定の Python バージョンを示すファイルhello.py：サンプルのエントリーポイント
以後、uv run、uv sync、uv lock のいずれかを実行すると、プロジェクト直下に 仮想環境 .venv と ロックファイル uv.lock が自動作成されます。
2) Python 本体のインストールと固定
uv は Python 自体も管理できます。プロジェクトごとに確実にバージョンを揃えたい場合は、この手順を踏みましょう。
# 例：Python 3.12 系をインストール
uv python install 3.12
# プロジェクトに 3.12 を固定（.python-version が更新される）
uv python pin 3.12
# インストール済みの一覧を確認
uv python list
uv python install は Python バイナリをダウンロードし、ローカルにインストールします。
uv python pin は .python-version に書き込み、以後の uv コマンドはそのバージョンを使用します。
3) ライブラリのバージョン管理
依存の追加
# ライブラリを追加（pyproject.toml と uv.lock に反映）
uv add httpx
# バージョン範囲を指定して追加
uv add "pandas>=2.2,<3"
# 開発専用の依存を追加
uv add --dev pytest
uv add --group lint ruff
uv add は 依存関係の宣言（pyproject.toml）とロック（uv.lock）、さらにインストールまでを一気に行います。--dev や --group で 依存の区分けも可能です。
依存の削除
# 依存を削除
uv remove httpx
環境の同期
# ロックファイルに基づいて環境を同期
uv sync
ロックファイル uv.lock と再現性
uv.lockは、OS・アーキテクチャ・Python バージョンまで含めた普遍的な解決結果を記録します- チームや CI/CD での環境のズレ防止に効果的
- uv では ロック＆同期は自動で行われます
- 完全固定で動かしたいときは
-frozen（ロック更新禁止）や-locked（ロックの変更禁止）を使用
既存の requirements.txt との連携
# requirements.txt から依存を取り込む
uv add -r requirements.txt
# uv.lock を requirements.txt にエクスポート
uv export --format requirements-txt -o requirements.txt
pipベースの既存環境や Docker ビルドで便利です。
4) コマンド実行 (uv run)
# プロジェクト環境（.venv）で Python を実行
uv run python -V
# Flask サーバを実行
uv add flask
uv run -- flask run -p 3000
# スクリプトを実行
uv run python hello.py
uv run は 実行前にロックと同期を自動確認し、毎回整った環境でコマンドを実行します。
仮想環境の手動アクティベートは不要です。
一時的な依存の追加
# 実行時だけ httpx を追加
uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"
プロジェクトの依存を汚さずに一時追加できます。
5) ツールの一時的な実行 (uvx)
# ruff を一時実行（プロジェクトを汚さない）
uvx ruff@latest check
# バージョンを厳密指定
uvx --from 'ruff==0.3.0' ruff check
# cowsay を試す
uvx pycowsay 'Hello, uv!'
uvx は uv tool run のエイリアスです。
必要な依存を一時的な仮想環境に入れてすぐ実行します。フォーマッタ・リンタ・各種 CLI ツールのお試しに最適です。
6) pip 互換インターフェース（必要な場合のみ）
既存スクリプトや職場の手順の都合で pip 互換の操作が必要な時は uv pip を使います。
# pip 互換のインストール
uv pip install requests
# パッケージ一覧
uv pip list
注意：
uv pipは環境に直接インストールする低レベル操作で、pyproject.tomlやuv.lockは更新しません。- プロジェクトの依存管理を続けたいなら、通常は
uv addを使いましょう。
4 まとめ
uv は 「速い」だけではなく、以下の機能がすべて一体化したパッケージマネージャです。
- Python 本体のバージョン管理（
uv python） - ロックファイルによるクロスプラットフォームの再現性（
uv.lock） - プロジェクトの自動同期と「常に整った環境」での実行（
uv run）
最初は uv init → uv add → uv run の 3 点セットから始め、必要に応じて uvx や uv export、--frozen を取り入れていくのがおすすめです。
5 参考リンク
公式ドキュメント
GitHubリポジトリ
Real Python ”Managing Python Projects With uv”
「Pythonパッケージ管理 [uv] 完全入門」
