uv コマンド一覧・逆引きチートシート｜pip・Poetryとの対応表

Python開発において、Rust製の超高速パッケージ・プロジェクト管理ツール「uv」が事実上の業界標準として定着しました。

しかし、「pipのあのコマンドはuvでどう書くのか」「Poetryからの移行時に対応するコマンドは何か」「スクリプト実行やバージョン固定はどうやるのか」など、実務中に手元でサッと確認したい場面は頻繁に訪れます。

この記事は、日常の開発業務で頻出するuvコマンドを瞬時に引けるようにまとめた実践チートシートです。「やりたいこと」から最短でコマンドに辿り着ける超高速リファレンスから、pip・Poetryとの独立対比表、初心者が陥りがちな注意点、検索されやすいFAQまでを網羅しています。ブックマークや日々のコーディングの手元資料としてご活用ください。

この記事でわかること
前提条件・対象読者
1. uv Quick Reference：まず覚える基本10コマンド
2. pip → uv 置き換え対応表（pipユーザー向け）
1. プロジェクト管理なら「uv add」、一時操作なら「uv pip」
3. Poetry → uv 置き換え対応表（Poetryユーザー向け）
4. uv / uv pip / uvx の違いと「よくある間違い」
1. 3つのモードの使い分け原則
2. 初心者がやりがちな間違い（アンチパターン）
5. プロジェクト管理コマンド（init / add / remove / lock / sync / tree）
6. Pythonバージョン管理コマンド（install / list / pin / find）
1. プロジェクトでのPython固定例
7. 実行・仮想環境コマンド（run / venv）
1. スクリプト・コマンド実行（uv run）
2. 仮想環境の手動作成（uv venv）
8. グローバルCLIツール管理（uvx / uv tool）
1. 単発実行（uvx）
2. グローバルインストール・永続管理（uv tool）
9. 実務設定・Docker・高度なコマンド
10. 検索クエリ型FAQ（よくある質問）
まとめ
次に読むおすすめ記事
参考情報

この記事でわかること

目的別コマンドに即座に到達できる「まず覚える基本10コマンド」
pipからuvへ移行するエンジニア向け「pip → uv 置き換え対応表」
Poetryからuvへ移行するエンジニア向け「Poetry → uv 置き換え対応表」
uv（プロジェクト管理）と uv pip（互換操作）と uvx（単発実行）の決定的な使い分け
実務で初心者が間違いやすいアンチパターンと正しい記述法
プロジェクト初期化、パッケージ追加・削除、Pythonバージョン管理、Docker運用の実務コマンド
検索クエリに応える逆引きFAQ

前提条件・対象読者

対象読者: Pythonの基礎知識があり、日々の開発でpip、Poetry、venv等を利用しているエンジニア
検証環境: Windows 11（PowerShell 7）および WSL2（Ubuntu 24.04 / 26.04）
対応バージョン: uv 0.11系以降（最終確認: 2026年9月）
補足: uvは活発に機能追加が行われているため、コマンド体系やオプションの最新状況は定期的に確認してください。

1. uv Quick Reference：まず覚える基本10コマンド

日常のPython開発の8割以上は、以下の10個のコマンドだけでカバーできます。手元で迷った際はこの表をご確認ください。

やりたいこと	uvコマンド	補足説明
プロジェクトを新規作成する	uv init	pyproject.tomlと.python-versionを生成
パッケージを追加する	uv add requests	pyproject.tomlとuv.lockを同時更新
開発用パッケージを追加する	uv add –dev pytest	[dependency-groups] dev に追加
パッケージを削除する	uv remove requests	依存ファイルと環境から完全削除
仮想環境をロックファイルと同期する	uv sync	uv.lockの内容を.venvへ正確に反映
スクリプトを実行する	uv run python main.py	仮想環境のアクティベート不要で即実行
テストやLinterを実行する	uv run pytest	仮想環境内のコマンドをそのまま実行
Pythonバージョンを導入する	uv python install 3.13	指定バージョンのPythonバイナリを自動取得
プロジェクトのPythonを固定する	uv python pin 3.13	.python-versionファイルを更新
CLIツールを一時実行する	uvx ruff check .	インストール不要でツールを即時実行

2. pip → uv 置き換え対応表（pipユーザー向け）

pipやvenvの操作に慣れているエンジニア向けに、従来のコマンドがuvでどう置き換わるかをまとめました。

uvでは「プロジェクト全体の依存関係を管理するコマンド（uv add等）」と「従来のpipと完全に同じ挙動をする互換コマンド（uv pip …）」の2系統が存在します。

従来のpip / venv コマンド	uv（プロジェクト管理推奨）	uv（pip互換モード）
pip install requests	uv add requests	uv pip install requests
pip install -r requirements.txt	uv add -r requirements.txt	uv pip install -r requirements.txt
pip install -U requests	uv lock –upgrade-package requests	uv pip install -U requests
pip uninstall requests	uv remove requests	uv pip uninstall requests
pip list	なし（uv treeでツリー確認）	uv pip list
pip freeze	なし（uv.lockで管理）	uv pip freeze
python -m venv .venv	uv sync（自動生成）	uv venv
source .venv/bin/activate	不要（uv run で自動解決）	source .venv/bin/activate
pip-compile requirements.in	uv lock	uv pip compile requirements.in
pip-sync requirements.txt	uv sync	uv pip sync requirements.txt

プロジェクト管理なら「uv add」、一時操作なら「uv pip」

新規開発やチーム開発では、pyproject.toml と uv.lock で整合性を保証する uv add や uv sync を使用するのが原則です。既存のDockerfileのビルド手順を壊さずに高速化したい場合や、一時的な検証作業を行う場合にのみ uv pip install を使用します。

3. Poetry → uv 置き換え対応表（Poetryユーザー向け）

Poetryからuvへ移行する場合、コマンドの体系が非常に近いため直感的に移行できます。主なコマンドの対応は以下の通りです。

Poetry コマンド	uv コマンド	処理内容
poetry new プロジェクト名	uv init プロジェクト名	新規プロジェクトのディレクトリ作成
poetry init	uv init	カレントディレクトリに設定ファイル作成
poetry add requests	uv add requests	パッケージの追加とロック
poetry add –group dev pytest	uv add –dev pytest	開発用依存グループへの追加
poetry remove requests	uv remove requests	パッケージの削除
poetry install	uv sync	ロックファイルに基づいた環境同期
poetry install –sync	uv sync	未使用パッケージの自動クリーン削除
poetry run python main.py	uv run python main.py	プロジェクト環境下でのスクリプト実行
poetry run pytest	uv run pytest	テストコマンドの実行
poetry lock	uv lock	ロックファイル（uv.lock）の更新
poetry lock –no-update	uv lock（デフォルト動作）	既存バージョンの再解決・固定
poetry show –tree	uv tree	依存関係ツリーの視覚的表示
poetry env info	uv venv –help（.venv直下）	仮想環境の確認

4. uv / uv pip / uvx の違いと「よくある間違い」

uvを使い始めた開発者が最も遭遇しやすい落とし穴が、コマンド体系の混同です。3つの使い分けを明確に把握しておきましょう。

3つのモードの使い分け原則

uv（プロジェクトモード）: uv init、uv add、uv sync、uv run など。 pyproject.toml と uv.lock を基点として、プロジェクト全体の環境を完全に再現・管理します。実務開発におけるメインの利用法です。
uv pip（pip互換モード）: uv pip install、uv pip freeze など。仮想環境（.venv）に対して直接パッケージを出し入れします。pyproject.toml や uv.lock には一切記録されません。
uvx（ツール実行モード）: uvx ruff check .、uvx black . など。単発で動かしたいCLIツールを、隔離された一時的な環境に自動ダウンロードして即座に実行します。PC本体やプロジェクト環境を汚しません。

初心者がやりがちな間違い（アンチパターン）

❌ 間違い例（プロジェクト内でpip互換コマンドを実行）
$ uv pip install fastapi

問題点:
ローカルの .venv にはパッケージが入りますが、pyproject.toml や uv.lock には記録されません。
後から git clone した他の開発者や CI/CD 環境で uv sync を実行した際、fastapi がインストールされずエラーになります。

⭕ 正しい手順（プロジェクトモードのコマンドを実行）
$ uv add fastapi

効果:
pyproject.toml に依存関係が記述され、uv.lock に正確なハッシュ値とバージョンが固定され、.venv も自動更新されます。

5. プロジェクト管理コマンド（init / add / remove / lock / sync / tree）

プロジェクトのライフサイクル全体を管理する主要コマンドの一覧です。

プロジェクト作成・初期設定

# カレントディレクトリにプロジェクトを作成（pyproject.tomlを作成）
uv init

# アプリケーション（実行可能スクリプト）として初期化
uv init --app my-app

# ライブラリ（配布用パッケージ）として初期化
uv init --lib my-lib

# Pythonバージョンを指定してプロジェクトを作成
uv init --python 3.12

パッケージの追加（uv add）

# 通常の依存関係を追加
uv add requests

# バージョン制約を指定して追加
uv add "fastapi>=0.115.0"

# 複数パッケージをまとめて追加
uv add httpx pydantic

# 開発用（dev）依存関係として追加
uv add --dev pytest pytest-asyncio ruff

# 特定の依存グループ（例: docs）に追加
uv add --group docs mkdocs

# Gitリポジトリから直接追加
uv add git+https://github.com/psf/requests.git

# ローカルのディレクトリから編集可能（editable）モードで追加
uv add -e ./my-local-pkg

# 既存の requirements.txt から一括追加
uv add -r requirements.txt

パッケージの削除（uv remove）

# 通常のパッケージを削除
uv remove requests

# 開発用グループから削除
uv remove --dev pytest

# 特定グループから削除
uv remove --group docs mkdocs

ロックファイル更新と環境同期（uv lock / uv sync）

# pyproject.toml に基づいて uv.lock を生成・更新
uv lock

# 特定のパッケージのみ最新バージョンへアップグレードしてロック
uv lock --upgrade-package requests

# すべてのパッケージを可能な限り最新へ一括アップグレード
uv lock --upgrade

# uv.lock の内容をローカルの .venv に完全同期
uv sync

# 開発用パッケージを除外して本番環境向けに同期（本番サーバー・Docker用）
uv sync --no-dev

# ロックファイルが存在しない・不整合な場合はエラーにする（CI用）
uv sync --frozen

# 依存関係ツリーをターミナルに階層表示
uv tree

# 特定パッケージがなぜ依存されているか逆引きツリーを表示
uv tree --invert --package urllib3

6. Pythonバージョン管理コマンド（install / list / pin / find）

uvはpyenvなどの外部ツールを使わずに、スタンドアロンのPythonバイナリを自動取得・切り替えできます。

操作内容	uvコマンド
利用可能なPythonバージョンを検索・一覧	uv python list
特定バージョンのPythonをインストール	uv python install 3.13
最新のパッチバージョンをインストール	uv python install 3.12
PyPyなどの別実装をインストール	uv python install pypy@3.10
プロジェクトで使用するバージョンを固定	uv python pin 3.13
インストール済みPythonのパスを確認	uv python find 3.13
不要になったPythonバイナリを削除	uv python uninstall 3.11

プロジェクトでのPython固定例

# プロジェクト内で実行すると .python-version が作成・更新される
uv python pin 3.13.0

# 以後、このディレクトリ配下で uv run を実行すると自動的に 3.13 で動作する
uv run python --version

7. 実行・仮想環境コマンド（run / venv）

仮想環境のアクティベート（source .venv/bin/activate）を行わずにスクリプトやツールを呼び出せるのがuvの強力な利点です。

スクリプト・コマンド実行（uv run）

# プロジェクトの仮想環境を使ってスクリプトを実行
uv run main.py

# モジュールを指定して実行
uv run -m pytest tests/

# 仮想環境に未インストールのパッケージを一時的に含めて実行
uv run --with pandas python -c "import pandas; print(pandas.__version__)"

# 外部スクリプトの先頭にあるインラインメタデータ（PEP 723）を認識して実行
uv run script_with_dependencies.py

仮想環境の手動作成（uv venv）

単発のスクリプト検証や、従来のpip互換フローを行いたい場合に使用します。

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

# Pythonバージョンを指定して仮想環境を作成
uv venv --python 3.12

# 仮想環境のディレクトリ名を指定して作成
uv venv myenv

# 作成した仮想環境のアクティベート（従来通り）
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# Linux / macOS / WSL:
source .venv/bin/activate

8. グローバルCLIツール管理（uvx / uv tool）

pipxの代替として、独立したPython製CLIツールを安全に実行・管理できます。

単発実行（uvx）

# Ruff（Linter）をインストールせずに単発実行
uvx ruff check .

# Black（Formatter）を実行
uvx black main.py

# 特定バージョンのツールを実行
uvx ruff@0.8.0 check .

# 引数を渡してツールを実行
uvx mypy src/

グローバルインストール・永続管理（uv tool）

# システム全体で使えるようにツールをインストール
uv tool install ruff

# 複数ツールをインストール
uv tool install black mypy httpie

# インストール済みツールの一覧表示
uv tool list

# 特定ツールを最新版にアップグレード
uv tool upgrade ruff

# すべてのツールを一括アップグレード
uv tool upgrade --all

# ツールのアンインストール
uv tool uninstall ruff

# ツールの実行PATHをシェルの設定ファイルに自動追加
uv tool update-shell

9. 実務設定・Docker・高度なコマンド

本番運用のコンテナ環境やエンタープライズ環境で頻出するコマンドと設定です。

Dockerfileでのベストプラクティス（マルチステージビルド）

uv公式のバイナリイメージからコピーし、キャッシュマウントを活用することでビルド時間を大幅に短縮できます。

FROM python:3.12-slim AS builder

# uvの実行ファイルを公式イメージからコピー
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

# 依存関係ファイルのみ先にコピーしてキャッシュを効かせる
COPY pyproject.toml uv.lock ./

# キャッシュをマウントして本番依存のみを同期インストール
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev --no-install-project

# ソースコードをコピーしてプロジェクト本体を同期
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

# アプリケーション起動
CMD ["/app/.venv/bin/python", "main.py"]

キャッシュ管理とオフライン実行

# キャッシュの使用容量とパスを確認
uv cache dir

# 不要になった古いキャッシュのみを削除
uv cache prune

# キャッシュを完全消去して空にする
uv cache clean

# ネットワーク通信を行わず、ローカルキャッシュのみを使って同期
uv sync --offline

プライベートパッケージインデックス（社内リポジトリ）連携

社内のプライベートリポジトリ（Artifactory、AWS CodeArtifact、GCP Artifact Registry等）を利用する場合、環境変数または設定ファイルで指定します。

# 環境変数で指定してパッケージ追加
UV_INDEX_URL="https://my-pypi.company.com/simple" uv add my-private-pkg

# 資格情報を付与して実行
UV_INDEX_URL="https://user:token@my-pypi.company.com/simple" uv sync

10. 検索クエリ型FAQ（よくある質問）

Q1: uvでパッケージをインストールするには何を使えばよいですか？

新規プロジェクトでは uv add パッケージ名 を使います。従来のpipのように仮想環境に直接インストールしたい場合のみ uv pip install パッケージ名 を使います。

Q2: uvで既存の requirements.txt を使うにはどうすればよいですか？

プロジェクトモードに移行する場合は uv init の後に uv add -r requirements.txt を実行します。既存の環境にそのまま入れたい場合は uv pip install -r requirements.txt を実行します。

Q3: uv sync と uv lock の違いは何ですか？

uv lock: pyproject.toml を解析して依存関係を確定し、uv.lock ファイルを生成・更新します（仮想環境のパッケージは変更しません）。
uv sync: uv.lock に記録されたパッケージ群を .venv にインストールし、環境を完全に一致させます。

Q4: uv run と通常の python コマンドの使い分けは？

プロジェクトディレクトリ内では常に uv run python main.py を使うのが推奨です。仮想環境の手動アクティベート（source .venv/bin/activate）を忘れてグローバル環境を壊すミスを完全に防止できます。

Q5: uvx とは？ pipxとの違いは何ですか？

uvx は pipx run に相当する機能です。CLIツール（RuffやBlackなど）をローカルに永続インストールすることなく、一時的なキャッシュ環境で爆速起動・実行できます。

Q6: uv自体のアップデートはどう行いますか？

スタンドアロンインストーラーで導入した場合は uv self update コマンドで最新版に更新できます。Homebrewやwingetで導入した場合は各パッケージマネージャー経由で更新します。

まとめ

uvは単なるpipの高速代替にとどまらず、Pythonバージョン管理、仮想環境の自動管理、依存関係の完全固定、そしてグローバルCLIツールの分離実行までを単一のバイナリで提供するオールインワンのモダン開発環境です。

日常業務では以下の4つの動詞を押さえておけば困りません。

作る: uv init
入れる: uv add
揃える: uv sync
走らせる: uv run

このチートシートを手元に置き、実務のPython開発のスピードと再現性を高めるリファレンスとしてお役立てください。

次に読むおすすめ記事

uvの詳しいインストール手順や、Windows（PowerShell）およびWSL2での環境構築、Poetryからの具体的な移行手順を確認したい方は、以下の入門ガイドもあわせて参考にしてください。

Python パッケージ管理ツール uv の使い方｜pip・Poetryとの比較と移行手順