👓

名探偵uv 〜消えたpipの謎〜 迷宮無しのパッケージ＆仮想環境管理ツールuvの真相を追え！

に公開
Python
pip
uv
tech

名探偵uv ～消えたpipの謎～

俺は Pythonエンジニアの、クロウ・シンイチ!!
幼なじみで同僚のモウムリ・ランとプロジェクトのデプロイ先に向かっていたとき──
黒づくめの「仮想環境の取引現場」を目撃した!!

依存関係を追うのに夢中になっていたオレは……
背後から近づいてくる “破壊的バージョンアップ” に気づかなかった……。

オレはそのツールに pip install で謎のパッケージを入れられ、
目が覚めたら──

環境が壊れていた!!

以前のコードをもう動かせないことがヤツら（ステークホルダー）にバレたら、
周りの同僚にも被害が及ぶ……。

AGASA博士（CTO）の助言で正体を隠すことにしたオレは、
ランに環境構築ツールの名前を聞かれて、
とっさにこう名乗った──

uv（ユーブイ） と。

ヤツら（黒づくめのレガシーツール）の動向を探るため、
開発現場に潜り込み、密かに依存地獄の真相を追い続ける……。

uv：小さくなっても機能は同じ！
迷宮無しで高速な名探偵!!

真実（正しいバージョン）はいつもひとつ!!

ということで、いまさらながら、uvについて、概要、活用手順、良く使うコマンド、など、
全情報一式をまとめてみます。

uv（ユーブイ）概要

uv は、Python の仮想環境・パッケージ・バージョン管理を統合した、Rust 製の高速ツールです。
pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv などの機能を一つにまとめ、よりシンプルで再現性の高い Python 開発環境を提供します。
公式では「An extremely fast Python package and project manager, written in Rust」などと紹介されています。

主な特徴（公式サイト参照）

  • 🚀 単一ツールで多機能を統合
    pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv などを置き換える、オールインワンのPython管理ツール。
  • ⚡ 10～100倍高速なパフォーマンス
    Rust による並列処理・キャッシュ最適化を活用し、インストールや依存解決を大幅に短縮。
  • 🗂️ 包括的なプロジェクト管理とロックファイル
    依存関係を完全に固定するユニバーサルロックファイル（uv.lock）を採用し、複数環境間での一貫性を確保。
  • ❇️ スクリプト実行と依存メタデータ対応
    uv run によりスクリプトを直接実行可能。コード内に依存メタデータをインラインで記述することもサポートしています。
  • 🐍 Python バージョンの管理・インストール
    uv python install や uv python pin などにより、Python のインストール・バージョン固定を簡単に実行できます。
  • 🛠️ Python パッケージツールの実行・管理
    uvx コマンド（uv tool run のエイリアス）で、Python パッケージとして公開されているツールを即時実行またはインストール可能。
  • 🔩 pip 互換の CLI
    既存の pip コマンドと互換性のあるインターフェースを備え、慣れた操作感のまま高速化を実現しています。
  • 🏢 Cargo スタイルのワークスペース対応
    Rust の Cargo と同様に、複数パッケージを統合管理するスケーラブルなワークスペース構成をサポート。
  • 💾 ディスク効率に優れたグローバルキャッシュ
    依存パッケージを共有キャッシュとして一元管理し、重複を排除。ストレージ使用量を削減。
  • ⏬ Rust や Python 不要のインストール
    curl や pip から直接インストールでき、Rust や Python の事前セットアップは不要。
  • 🖥️ クロスプラットフォーム対応
    macOS / Linux / Windows すべての主要 OS で利用可能。

公式情報

補足:
uv は Python Linter「ruff」を開発した Astral 社 により開発されています。
高速性・互換性・再現性を兼ね備えた、次世代の Python 開発基盤として注目されています。

uv の活用手順（Windows 版を主に記載）

インストール

PowerShell を開き、以下を実行します：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • なお、Python 自体のインストールも uv で実施可能です。
  • 事前に Python をインストールしておく必要はありません。

実行結果例：

Downloading uv 0.9.7 (x86_64-pc-windows-msvc)
Installing to C:\Users\yuu_w\.local\bin
  uv.exe
  uvx.exe
  uvw.exe
everything's installed!

macOS／Linux の場合（ご参考）

# 一例：bash シェルから
curl -LsSf https://astral.sh/uv/install.sh | sh

# Homebrew
brew install uv

バージョン確認

uv self version

出力例：

uv 0.9.7 (0adb44480 2025-10-30)

Python プロジェクトの作成

1. プロジェクト初期化

uv init uvtest01
  • プロジェクト名のフォルダが作られ、基本的なファイルが自動生成されます。

2. プロジェクトディレクトリへ移動

cd .\uvtest01\

3. 自動生成されるファイル

.gitignore
.python-version
main.py
pyproject.toml
README.md

※ バージョンにより、微妙に生成されるファイルが異なるようです。

4. pyproject.toml の内容（例）

[project]
name = "uvtest01"           # プロジェクト名
version = "0.1.0"           # バージョン
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []           # 依存パッケージ一覧

Python のインストールと指定

Python 3.14 をインストール

uv python install 3.14

出力例：

Installed Python 3.14.0 in 6.39s
 + cpython-3.14.0-windows-x86_64-none (python3.14.exe)

インストール済み Python 一覧

uv python list

現在のプロジェクトが使用している Python の確認

uv run python -c "import sys; print(sys.prefix)"

.python-version の確認

cat .python-version

出力例：

3.12

Python バージョンを固定（pin）

uv python pin 3.14

これにより、.python-version が 3.14 に固定されます。

仮想環境でのPython実行

実行

仮想環境のアクティベート無しでも、uv run で直接実行が可能です：

uv run main.py

出力例：

Using CPython 3.14.0
Creating virtual environment at: .venv
Hello from uvtest01!

実行後、以下の仮想環境用ファイル／フォルダが生成されます：

.venv/
uv.lock

パッケージ管理

インストール済みパッケージ一覧

uv pip list

パッケージの追加

uv add パッケージ名

  • または、uv pip install パッケージ名 でも可。

  • パッケージをインストールすると、

    • pyproject.toml の [dependencies] に追記されます。
    • uv.lock に依存関係を含めた全パッケージのバージョンが記録されます。→複数環境での再現性が確保されます。

パッケージの削除

uv remove パッケージ名

依存パッケージの一括インストール

uv sync

（uv.lock に基づいて環境を整備）

仮想環境の操作

仮想環境を作成

uv venv <仮想環境名>

※ 仮想環境名を省略すると、デフォルトで .venv が作成されます。
uv run main.py を実行している場合は、すでに .venv が存在していることがあります。

※ 基本的には、デフォルトの名前 .venv にしておく方が、IDE／ツール連携時に便利です。

仮想環境をアクティベート

.venv\Scripts\activate

実行例：

PS C:\uv\uvtest01> .venv\Scripts\activate
(uvtest01) PS C:\uv\uvtest01> python .\main.py

仮想環境を終了

deactivate

⚠️ uv を使う際の注意点

uv を導入すると、従来の pip や virtualenv の使い方とは少し考え方が変わります。
特に以下の点を理解しておくと、環境の不整合やトラブルを避けられます。

① pip を直接使わないこと

uv 環境では、uv add <パッケージ名> のコマンドを使うことが推奨されます。
仮想環境を有効にせずに pip install を実行すると、ライブラリが システム全体にインストール され、uv が管理しているプロジェクト環境には反映されない可能性があります。

② pip での操作は uv.lock に反映されない

仮に仮想環境をアクティブな状態で pip install を使っても、ライブラリ自体はその環境に入るものの、uv が管理する uv.lock や pyproject.toml は自動で更新されません。
その結果、実際の環境と uv の記録（ロックファイル） がズレてしまい、再現性が低下するリスクがあります。

③ uvx 実行時の環境はプロジェクトの環境と分離されている

uvx（または uv tool run）でツールを実行するときは、プロジェクトとは独立した一時仮想環境が使用されます。公式ドキュメントにも「ツールがプロジェクトの依存を必要とする場合は uv run を使うべき」と明記されています。
この設計は、ツールの依存関係をプロジェクトに影響させずに実行できるという利点がありますが、逆に「ツールとプロジェクト依存を共有したい」場合には挙動が異なるので注意が必要です。

④ 既存プロジェクトの移行は慎重に

既に pipenv／poetry／requirements.txt などで構成されたプロジェクトを uv に移行する際は、依存解決方式・ロックファイル形式・仮想環境生成の挙動などが異なるため、クリーンな環境で動作確認を行ってから移行作業を進めるのが安全です。
公式ブログでも「uv は pip／pip-tools から始まり、プロジェクト、スクリプト、Python 本体管理まで統合する ‘Cargo for Python’ を目指している」という記述があります。

✅ 注意点まとめ

uv は、Python 環境管理・依存解決・ツール実行を高速化し、再現性を高める強力なオールインワンツールです。
ただし、従来の pip や virtualenv と併用して使ったときに生じるズレや混乱が、実運用で最も多くのトラブルを引き起こします。
そのため、導入直後は以下のような“ルール”を意識すると良いでしょう：

  • 「uv で構築した環境は、原則として uv のコマンドでのみ管理する」
  • 「pip や他ツールのコマンドを使う場合は、その作用範囲を明確に理解する」
    このような運用を徹底すれば、ロックファイルのズレ・依存環境の不整合・複数環境間の再現性低下といったリスクを大幅に軽減できます。

コマンドまとめ

🔧 uv よく使われるコマンド一覧

操作内容 コマンド例 説明
バージョン確認 uv self version uv のバージョンを確認
uv の自己アップデート uv self update uv 自体を最新バージョンに更新
新規プロジェクト作成 uv init <プロジェクト名> 新しい Python プロジェクトを初期化
プロジェクト情報表示 uv project show 現在のプロジェクト情報を表示
Python のインストール uv python install 3.12 指定したバージョンの Python をインストール
Python の一覧表示 uv python list インストール済みの Python バージョン一覧
Python の固定（pin） uv python pin 3.12 .python-version に指定バージョンを固定
Python のアンインストール uv python uninstall 3.12 インストール済みの Python を削除
Python の実行 uv run python uv 管理下の Python を実行
スクリプト実行 uv run main.py 仮想環境を自動生成し、スクリプトを実行
依存関係インストール uv sync pyproject.toml / uv.lock に基づき依存関係を同期
パッケージ追加 uv add <パッケージ名> パッケージを追加して pyproject.toml に記録
パッケージ追加（バージョン指定） uv add <パッケージ名>==<バージョン> 特定バージョンのパッケージを追加
パッケージ削除 uv remove <パッケージ名> 指定パッケージを削除
パッケージ一覧表示 uv pip list 仮想環境内にインストール済みパッケージ一覧を表示
パッケージ情報表示 uv pip show <パッケージ名> 指定パッケージの詳細情報を表示
requirements.txt 出力 uv export -o requirements.txt 現在の依存を requirements.txt として書き出し
パッケージを再構築（再インストール） uv sync --reinstall 依存関係を強制再インストール
仮想環境作成 uv venv デフォルトの .venv 仮想環境を作成
仮想環境作成（任意名） uv venv <フォルダ名> 指定名の仮想環境を作成
仮想環境起動（Windows） .venv\Scripts\activate 仮想環境をアクティベート
仮想環境起動（Mac/Linux） source .venv/bin/activate Mac / Linux 用のアクティベート
仮想環境離脱 deactivate 仮想環境を終了して元の環境に戻る
仮想環境削除 uv venv remove .venv を削除（存在する場合）
Python 実行環境確認 uv run python -V 現在の Python バージョンを確認
tree 表示 uv tree 依存関係のツリーを階層的に表示
ロックファイル確認 cat uv.lock 依存関係ロックファイルの内容を確認
依存関係検証 uv check 依存関係の整合性や競合をチェック
ツールの実行（uvx） uvx <ツール名> 一時環境で Python ツールを実行（例：uvx ruff check .）
ツールのインストール uv tool install <ツール名> 開発ツールを永続的にインストール（例：uv tool install ruff）
ツール一覧表示 uv tool list インストール済みツール一覧
ツール削除 uv tool uninstall <ツール名> ツールをアンインストール
プロジェクトクリーンアップ uv clean キャッシュ・一時ファイルなどを削除
キャッシュパス表示 uv cache dir uv のキャッシュディレクトリのパスを表示
キャッシュクリア uv cache clear すべてのキャッシュを削除
ワークスペース作成 uv workspace init Cargo スタイルのワークスペースを初期化
ワークスペース構成確認 uv workspace show ワークスペースの状態を表示
テスト実行（例） uv run pytest 仮想環境を使ってテストを実行
Lint実行（例） uvx ruff check . 一時環境で ruff による Lint を実行
依存関係を requirements.txt に変換 uv export --format=requirements 他ツール用に依存情報を書き出し
Lockファイル生成 uv lock 依存関係をロックして uv.lock を生成
依存関係更新 uv update 依存関係を最新に更新
依存関係更新（特定パッケージ） uv update <パッケージ名> 指定パッケージのみ更新
パッケージを再解決 uv resolve 依存を再解決（lock再生成含む）
現在の環境情報出力 uv info Python / 仮想環境 / OS などの情報を表示
ヘルプ表示 uv --help 利用可能なコマンド一覧を表示

💡 よく使う組み合わせ例

用途 コマンド例
新しいプロジェクトを作成して起動 uv init myapp && cd myapp && uv run main.py
パッケージの追加と実行 uv add fastapi && uv run main.py
依存関係を一括更新 uv update && uv sync
ツール実行（ruffやblackなど） uvx ruff check .、uvx black .
Pythonバージョンを変更 uv python install 3.13 && uv python pin 3.13 && uv sync
環境リセット uv clean && uv sync --reinstall

🧠 補足

  • uvx は ツール実行用のサブコマンド。
    例：uvx ruff、uvx black、uvx mypy など。
    これにより、グローバル環境を汚さずに一時的にツールを実行できます。

  • uv tree は依存関係を確認するのに非常に便利です。
    例：

    uv tree
requests==2.31.0
├── certifi==2024.7.4
├── charset-normalizer==3.3.2
├── idna==3.7
└── urllib3==2.2.1

  • uv clean はキャッシュや一時ビルドを削除するコマンド。
    ディスク容量を圧迫している場合や環境のリセットに有用です。

補足／移行検討時のポイント

  • uv は既存の pip／pip-tools などからの移行を “ドロップイン” で可能とする設計になっており、既存プロジェクトに大きな構成変更なしに導入できるケースが多いです。
  • ただし、企業環境や特定ツール群（例えば tox、conda、複雑なビルド構成）を含むプロジェクトでは、互換性検証・移行テストを行うべきです。
  • lock ファイル (uv.lock) による完全な依存固定が可能ですが、プラットフォーム間（Windows ↔ Linux ↔ macOS）での可搬性には制約があることがあります。現時点では汎用プラットフォーム横断の lock に関する機能が他ツールと比べて限定的という指摘もあります。
  • uvx コマンドを多用することで、開発ツール（ruff、black、mypy など）をプロジェクト依存と切り離して実行できますが、逆にいえば「プロジェクト環境と同一 Python バージョンを使わない」設定になりやすいので、CI／ローカルでの一貫性確保に注意が必要です。

総まとめ

uv は、Python の環境構築／依存管理／ツール実行という、従来バラバラだった複数ツールの統合を目指した、非常に高速かつモダンなツールです。
特に 速度 と 再現性 に重点が置かれており、Rust 製という背景からインストール・依存解決・キャッシュ管理などにおいて他ツールと差別化されています。
既存の pip や virtualenv、poetry ワークフローを改善・更新したいプロジェクトには、有力な選択肢となり得ます。
ただし、移行や運用には多少の検討・テストが必要ですので、段階的な導入・検証をおすすめします。

Discussion