Zenn
🌅

初めてのuv入門｜uvコマンドガイド：uv pip インターフェース編

に公開
Python
uv
tech

知識は武器とかけまして、レゴブロックと解く、その心は――
今日もKnowledge Oasisへようこそ
案内人はkoふみです
本日のテーマは『uv pip インターフェース編』

はじめに

Pythonプロジェクトの開発では、依存関係の管理や仮想環境の操作が欠かせません。pip を使ってパッケージをインストールするのはよくある手順ですが、環境の再現性やスピードをより高めたい場面もありますよね。そこで登場するのが、uv pip インターフェースです。uv pip を使うと、uv venv で仮想環境を作成・管理しつつ、従来の pip と同様のコマンド体系でパッケージを扱えるうえに、より一貫性のある環境構築やロック機能を利用できます。この記事では、uv venv から始まり、パッケージ管理や環境検査、ロック・同期までをカバーする各コマンドについて、概要から使い方、主なオプション、ポイントまで詳しく解説します。

対象読者

  • 既存の pip ワークフローをそのまま活かしつつ、より高速かつ再現性の高い環境管理を行いたいエンジニア
  • プロジェクトごとに仮想環境を隔離しながら、従来の pip コマンドと同じ感覚で操作したい方
  • requirements.txt やロックファイルを使った環境再現を自動化し、CI/CD やチーム開発での依存管理をシンプルにしたい方

コマンド解説

uv venv: 仮想環境を作成する

概要

uv venv は、プロジェクトごとに仮想環境を作成するコマンドです。デフォルトではカレントディレクトリに .venv という名前の仮想環境を作成しますが、任意の名前やパス、さらには特定の Python バージョンを指定して環境を構築することも可能です。

使い方

$ uv venv
# カレントディレクトリに .venv を作成

$ uv venv my-env
# my-env という名前で仮想環境を作成

$ uv venv --python 3.11
# Python 3.11 の環境を .venv として作成

主なオプション

  • my-env：任意のディレクトリ名・パスを指定すると、その場所に仮想環境を作成します。
  • --python <バージョン>：システムに存在する指定バージョンの Python を利用して仮想環境を作成します。指定のバージョンがない場合、uv が自動でダウンロードしてくれます。

ポイント

  • 一度 uv venv を実行すると、以降の uv pip コマンドや uv run コマンドは自動的にその仮想環境を検出して利用します。手動での source .venv/bin/activate は不要です。
  • 仮想環境を終了するには、生成された環境内の deactivate コマンドで簡単に切り替えができます。

uv pip install: パッケージをインストールする

概要

uv pip install は、pip install の代替として、現在アクティブな仮想環境（uv venv で作成した環境）に対して Python パッケージをインストールするコマンドです。pip と同じ感覚で複数パッケージやバージョン指定、さらには Git リポジトリやローカルディスクからのインストールもサポートしています。

使い方

$ uv pip install flask
# Flask をインストール

$ uv pip install "flask[dotenv]"
# Flask の dotenv エクストラを有効にしてインストール

$ uv pip install ruff==0.3.0
# Ruff を特定バージョンでインストール

$ uv pip install "git+https://github.com/astral-sh/ruff"
# GitHub リポジトリから直接インストール

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

主なオプション

  • -r <ファイル名>：requirements.txt や pyproject.toml など、ファイルに列挙された複数のパッケージを一括インストール。
  • --extra <グループ名>：pyproject.toml 内のオプショナル依存グループを参照してインストール（例：--extra foo）。
  • --all-extras：すべてのオプショナル依存を有効にしてインストール。
  • --group <グループ名>：指定した依存グループ（PEP 621 準拠）をインストール。
  • --python <パスまたはバージョン>：デフォルトの仮想環境以外の環境にインストールしたい場合に指定。
  • --system：システム Python 環境にインストール（仮想環境を経由せず）。

ポイント

  • uv pip install は、パッケージの解決速度が非常に高速であると同時に、グローバルキャッシュを活用して重複インストールを防ぎます。
  • --group や --extra オプションを使うと、pyproject.toml に宣言された依存関係をそのまま反映できるため、手動でバージョンを合わせる手間が減ります。
  • 既に同じ名前のパッケージがインストールされている場合、同じバージョンかどうかをチェックし、必要であればアップグレードします。

uv pip show: インストール済みパッケージの情報を表示する

概要

uv pip show は、指定したパッケージが現在の環境（アクティブな仮想環境またはシステム環境）にインストールされているかを確認し、その詳細情報（バージョン、依存関係、インストールパスなど）を表示するコマンドです。複数パッケージを同時に指定することもできます。

使い方

$ uv pip show numpy
# numpy のインストール情報を表示

$ uv pip show flask ruff
# flask と ruff の情報を両方表示

主なオプション

  • 特に主要なオプションはなく、調べたいパッケージ名をスペース区切りで指定するのみです。

ポイント

  • 複数パッケージを一度に指定すると、各パッケージの情報が順に出力されます。
  • 出力される情報には、パッケージの要約（Summary）、ホームページ（Home-page）、作者（Author）、ライセンス（License）などが含まれ、トラブルシューティングやドキュメント参照時に便利です。

uv pip freeze: インストール済みパッケージを requirements 形式で表示

概要

uv pip freeze は、現在の環境（アクティブな仮想環境またはシステム環境）にインストールされているすべてのパッケージとそのバージョンを、requirements.txt 形式で表示するコマンドです。ファイルにリダイレクトすれば、そのまま lockfile のベースとしても使えます。

使い方

$ uv pip freeze
# パッケージ名==バージョン の一覧を requirements 形式で表示

$ uv pip freeze > requirements.txt
# requirements.txt に出力してロックファイル代わりに保管

主なオプション

  • こちらも特にオプションは不要で、単に実行すると現在の全パッケージ一覧を出力します。

ポイント

  • uv pip install や uv pip uninstall で環境が変化するたびに uv pip freeze を実行し、チーム共有用の requirements.txt を更新すると、環境の再現性を保ちやすくなります。
  • requirements.txt を使って別のマシンで uv pip install -r requirements.txt すれば、同じ依存セットを再現できます。

uv pip check: 環境の整合性を検査する

概要

uv pip check は、インストール済みパッケージ間で依存関係の衝突や欠落がないかを検査し、問題があれば警告を出力するコマンドです。手順を分けて複数回に分けてインストールした際などに、依存関係が矛盾していないか確認できます。

使い方

$ uv pip check
# 環境内の全パッケージを検査し、問題があれば一覧で表示

主なオプション

  • 特別なオプションはなく、コマンドを実行するだけでチェックが走ります。

ポイント

  • プロダクション環境や CI/CD パイプラインの一部として組み込むと、意図しない依存衝突を事前に検知できます。
  • uv pip install 時には基本的に依存解決が行われるため、通常は大きな問題は発生しにくいですが、手動でパッケージを追加した後などに一度 uv pip check を実行しておくと安心です。

uv pip list: インストール済みパッケージの一覧を表示する

概要

uv pip list は、環境内にインストールされているすべてのパッケージを一覧表示するコマンドで、pip list と同等の機能を提供します。JSON 形式での出力や、特定フォーマットを指定して表示することも可能です。

使い方

$ uv pip list
# パッケージ名とバージョンをターミナルに一覧表示

$ uv pip list --format json
# JSON 形式で出力して他ツールと連携しやすくする

主なオプション

  • --format json：JSON 形式でパッケージ一覧を出力。
  • --format columns：デフォルトのタブ区切り形式で表示（省略時）。
  • --outdated：アップグレード可能なパッケージだけを表示。
  • --uptodate：最新バージョンのパッケージだけを表示。

ポイント

  • uv pip list は、uv pip freeze とは異なり、バージョン指定なしですべてのパッケージをモダンな表形式や JSON 形式で確認できます。
  • チーム開発で「どのバージョンがインストールされているか」を確認したいときに便利なコマンドです。

uv pip uninstall: パッケージをアンインストールする

概要

uv pip uninstall は、指定したパッケージを環境から削除するコマンドで、pip uninstall と同じように機能します。複数パッケージを同時に指定して一気にアンインストールすることも可能です。

使い方

$ uv pip uninstall flask
# Flask をアンインストール

$ uv pip uninstall flask ruff
# Flask と Ruff をまとめてアンインストール

主なオプション

  • -y：確認なしでアンインストールを実行（pip uninstall -y と同様）。
  • 複数パッケージ名をスペース区切りで指定すると、一度にすべてアンインストールできます。

ポイント

  • uv pip uninstall を実行しても、そのパッケージに依存している他のパッケージは自動で削除されません。必要に応じて uv pip list や uv pip freeze で依存関係を確認し、不要になった依存を手動でアンインストールしてください。
  • 環境のクリーンアップ時やバージョンをゼロから見直したい場合は、アンインストール後に uv pip freeze や uv pip list で状態を確認しましょう。

uv pip tree: 依存関係ツリーを表示する

概要

uv pip tree は、現在の環境（アクティブな仮想環境またはシステム環境）にインストールされているパッケージの依存関係をツリー形式で可視化するコマンドです。pipdeptree と同様の形式で表示され、どのパッケージがどの依存を持っているかを一目で把握できます。

使い方

$ uv pip tree

以下は、仮想環境内に cowsay と rich をインストールしている場合の出力例です（一例）：

$ uv pip tree
cowsay v6.1
rich v13.9.4
├── markdown-it-py v3.0.0
│   └── mdurl v0.1.2
├── pygments v2.19.1
└── typing-extensions v4.12.2

主なオプション

  • --allow-insecure-host, --trusted-host <ホスト名>: 認証局で署名されていないホストに対して、SSL 検証をスキップして接続します。複数回指定可能。
  • --prune <パッケージ名>: 指定したパッケージをツリー表示から除外します。
  • --python <インタープリタパスまたはバージョン>: 依存ツリーを表示する対象の Python インタープリタを指定します。

ポイント

  • uv pip tree を使うことで、大規模プロジェクトで複雑な依存関係を視覚的に把握でき、バージョン衝突の原因や不要な依存パッケージを特定しやすくなります。
  • たとえば、あるパッケージをアンインストールする前に uv pip tree を実行すると、「削除すると影響が及ぶ範囲」を確認できるため、安全に環境の整理が可能です。

uv pip compile: lockfile を生成する

概要

uv pip compile は、pyproject.toml や requirements.in などに宣言された依存関係を解決し、正確なバージョンをピン留めした requirements.txt 形式のファイルを生成するコマンドです。これにより、同じ依存セットを再現性高くインストールできます。

使い方

$ uv pip compile pyproject.toml -o requirements.txt
# pyproject.toml の依存を解決し requirements.txt に書き出し

$ uv pip compile requirements.in -o requirements.txt
# requirements.in の依存を解決して書き出し

$ echo "ruff" | uv pip compile - -o requirements.txt
# stdin から 'ruff' を受け取りロックを生成

主なオプション

  • -o <出力ファイル>（または --output-file）：生成結果をファイルに書き出す。
  • --upgrade-package <パッケージ名>：特定パッケージだけをアップグレードして再度ロックを生成。
  • --upgrade：すべての依存を最新適合バージョンに更新してロックを再生成。
  • --extra <グループ名>：pyproject.toml のオプショナル依存を有効化してロックを生成。
  • --all-extras：すべてのオプショナル依存を含めてロックを生成。
  • --group <グループ名>：依存グループをピン留めしてロックを生成。
  • --constraint <constraints.txt>：制約ファイルを適用してロック生成。
  • --override <overrides.txt>：上書きファイルを適用してロック生成。
  • --no-strip-extras：extras を保持して出力（デフォルトは --strip-extras）。
  • --emit-index-url：インデックス URL を含めて出力。

ポイント

  • 既存の requirements.txt にピン留め済みのバージョンがある場合、再度 uv pip compile を実行してもそのバージョンは維持されます。新しいバージョンを使いたい場合は --upgrade または --upgrade-package を指定してください。
  • lockfile を生成した後は、CI/CD やチームメンバー間で共有し、uv pip sync で厳密に同じ環境を再現しましょう。
  • pyproject.toml や requirements.in だけでなく、setup.py からも依存を読み取れるため、既存の多様なプロジェクト構成に対応可能です。

uv pip sync: lockfile と環境を同期する

概要

uv pip sync は、uv pip compile などで生成したロックファイル（requirements.txt など）や pyproject.toml で宣言された依存をもとに、仮想環境を完全に同期するコマンドです。不要なパッケージはアンインストールし、不足しているパッケージはインストールすることで、環境をロックファイルの内容と一致させます。

使い方

$ uv pip sync requirements.txt
# requirements.txt をもとに環境を同期

$ uv pip sync pyproject.toml
# pyproject.toml の依存をもとに環境を同期

主なオプション

  • --python <パスまたはバージョン>：異なる環境に同期したい場合に指定。
  • --system：仮想環境ではなくシステム環境を同期（--python と同様）。
  • --skip-build-isolation：ビルド時の分離をスキップしてインストールする（特殊な事情がある場合のみ）。

ポイント

  • uv pip install とは異なり、環境に存在するがロックファイルに含まれていないパッケージはすべて削除されるため、再現性が非常に高くなります。
  • チーム開発や本番環境デプロイ前に実行すれば、ローカル環境と同じパッケージセットを正確に反映できます。
  • コンテナ環境や CI/CD では、uv pip compile → uv pip sync の順に実行すると、同一の環境を短時間で構築可能です。

まとめ

この記事では、uv pip インターフェースにおける主要コマンド10種類について、以下の構成で解説しました。

  1. uv venv：仮想環境の作成と管理
  2. uv pip install：パッケージのインストール（複数パッケージ、バージョン指定、ローカル/Git からのインストール）
  3. uv pip show：インストール済みパッケージの詳細情報表示
  4. uv pip freeze：インストール済みパッケージを requirements.txt 形式で出力
  5. uv pip check：環境の依存衝突や欠落を検査
  6. uv pip list：インストール済みパッケージの一覧表示（JSON 形式も可）
  7. uv pip uninstall：パッケージのアンインストール
  8. uv pip compile：依存を解決して lockfile（requirements.txt）を生成
  9. uv pip sync：ロックファイルと環境を完全に同期

uv pip を使うことで、仮想環境の作成からパッケージのインストール、検査、ロック、同期まで、Python 環境管理が一貫して行えます。これにより、開発中の環境差異を最小化し、チームや CI/CD での再現性を高めることができます。ぜひこの記事を参考に、あなたの開発ワークフローにも uv pip を取り入れてみてください。

知識のひとつひとつは小さなレゴブロック
でも、組み合わせれば世界を変えるアイディアをカタチにする武器になる！

またKnowledge Oasisでお会いしましょう
案内人はkoふみでした

Discussion