メインコンテンツへスキップ
Toolsbase Logo

uv コマンド一覧

Python高速パッケージマネージャー uv のプロジェクト管理・Python版管理・pip互換・設定コマンドと実践ワークフローをまとめたリファレンス。カテゴリ検索とワンクリックコピーで開発中にすばやく確認できます。

使い方使い方を開く
  1. 1

    カテゴリで絞り込む

    プロジェクト管理、Python・ツール管理、pip互換、設定、ワークフローを切り替えて目的の情報にすばやく到達できます。

  2. 2

    検索で詳細を探す

    検索欄でコマンド名、オプション解説、使用例をまとめて部分一致検索できます。

  3. 3

    コピーして実行

    カードのコピーボタンからコマンドを取得し、そのままターミナルで実行できます。

uv run

コマンドやスクリプトを仮想環境内で実行します。

ポイント

  • --with <pkg>: 一時的に追加パッケージを使って実行。
  • --python <ver>: 特定のPythonバージョンで実行。

使用例

uv run python app.py
プロジェクトの仮想環境でスクリプトを実行。
uv run --with requests python fetch.py
requestsを一時追加して実行。

uv init

新しいPythonプロジェクトを作成します。

ポイント

  • --name <name>: プロジェクト名を指定。
  • --python <ver>: 使用するPythonバージョンを指定。

使用例

uv init my-project
my-projectディレクトリに新規プロジェクトを作成。
uv init --python 3.12
Python 3.12を指定してプロジェクトを初期化。

uv add

プロジェクトに依存パッケージを追加します。

ポイント

  • --dev: 開発用依存として追加。
  • --optional <group>: オプショナル依存グループに追加。

使用例

uv add flask
Flaskを依存パッケージに追加。
uv add --dev pytest ruff
pytestとruffを開発用依存に追加。

uv remove

プロジェクトから依存パッケージを削除します。

ポイント

  • --dev: 開発用依存から削除。
  • --optional <group>: オプショナル依存グループから削除。

使用例

uv remove flask
Flaskを依存パッケージから削除。
uv remove --dev pytest
pytestを開発用依存から削除。

uv sync

ロックファイルに基づいてプロジェクトの環境を同期します。

ポイント

  • --frozen: ロックファイルを更新せずに同期。
  • --no-dev: 開発用依存を除外して同期。

使用例

uv sync
ロックファイルに基づいて環境を同期。
uv sync --frozen --no-dev
CI向け: ロック固定で本番依存のみ同期。

uv lock

プロジェクトのロックファイル（uv.lock）を更新します。

ポイント

  • --upgrade: 全パッケージを最新バージョンに更新。
  • --upgrade-package <pkg>: 特定パッケージのみ更新。

使用例

uv lock
ロックファイルを再生成。
uv lock --upgrade-package flask
Flaskのみ最新バージョンにロック更新。

uv export

ロックファイルを別の形式でエクスポートします。

ポイント

  • --format requirements-txt: requirements.txt形式で出力。
  • --no-dev: 開発用依存を除外。

使用例

uv export --format requirements-txt > requirements.txt
requirements.txt形式でエクスポート。
uv export --format requirements-txt --no-dev
本番依存のみrequirements.txtで出力。

uv tree

プロジェクトの依存関係ツリーを表示します。

ポイント

  • --depth <n>: ツリーの深さを制限。
  • --invert: 逆方向の依存関係を表示。

使用例

uv tree
依存関係ツリーを表示。
uv tree --depth 1
直接依存のみ表示。

uv version

プロジェクトのバージョンを表示・更新します。

ポイント

  • --bump <type>: major/minor/patchでバージョンを上げる。
  • --output-format json: JSON形式で出力。

使用例

uv version
現在のバージョンを表示。
uv version --bump minor
マイナーバージョンを上げる。

uv venv

仮想環境を作成します。

ポイント

  • --python <ver>: 使用するPythonバージョンを指定。
  • --seed: pip, setuptools, wheelを仮想環境にプリインストール。

使用例

uv venv
.venvディレクトリに仮想環境を作成。
uv venv --python 3.12 .venv312
Python 3.12で指定ディレクトリに作成。

uv build

PythonパッケージをsdistやWheelにビルドします。

ポイント

  • --sdist: ソースディストリビューションのみ作成。
  • --wheel: Wheelのみ作成。

使用例

uv build
sdistとWheelの両方を生成。
uv build --wheel
Wheelのみ生成。

uv publish

ビルドしたパッケージをPyPIにアップロードします。

ポイント

  • --token <token>: PyPIのAPIトークンを指定。
  • --publish-url <url>: カスタムリポジトリURLを指定。

使用例

uv publish
distディレクトリの成果物をPyPIにアップロード。
uv publish --publish-url https://test.pypi.org/legacy/
TestPyPIにアップロード。

uv format

プロジェクトのPythonコードをフォーマットします。

ポイント

  • --check: フォーマット変更が必要か確認のみ行う。
  • --diff: 変更差分を表示。

使用例

uv format
プロジェクト全体をフォーマット。
uv format --check
フォーマット違反がないか確認。

uv python install

Pythonバージョンをインストールします。

ポイント

  • uv python install 3.12: 指定バージョンをインストール。
  • uv python install 3.11 3.12: 複数バージョンを同時インストール。

使用例

uv python install 3.12
Python 3.12をインストール。
uv python install 3.11 3.12 3.13
3バージョンを同時にインストール。

uv python list

利用可能なPythonバージョンを一覧表示します。

ポイント

  • --all-versions: マイナーバージョンも含めて全て表示。
  • --only-installed: インストール済みのみ表示。

使用例

uv python list
利用可能なPythonバージョンを表示。
uv python list --only-installed
インストール済みバージョンのみ表示。

uv python find

指定条件に合うPythonインタプリタを検索します。

ポイント

  • uv python find 3.12: 3.12系のインタプリタを検索。
  • uv python find cpython: CPython実装を検索。

使用例

uv python find 3.12
Python 3.12のパスを表示。
uv python find
デフォルトのPythonインタプリタパスを表示。

uv python pin

プロジェクトで使用するPythonバージョンを固定します。

ポイント

  • .python-versionファイルにバージョンを記録。
  • --resolved: 完全なバージョン文字列で固定。

使用例

uv python pin 3.12
Python 3.12に固定（.python-versionに記録）。
uv python pin 3.12 --resolved
完全なバージョン文字列で固定。

uv python uninstall

インストール済みのPythonバージョンを削除します。

ポイント

  • uv python uninstall 3.11: 指定バージョンを削除。
  • --all: 全てのマネージドPythonを削除。

使用例

uv python uninstall 3.11
Python 3.11を削除。
uv python uninstall --all
uvで管理している全Pythonを削除。

uv python upgrade

インストール済みのPythonバージョンをアップグレードします。

ポイント

  • uv python upgrade 3.12: 3.12系の最新パッチに更新。
  • パッチバージョン（3.12.x→3.12.y）単位で更新。

使用例

uv python upgrade 3.12
Python 3.12を最新パッチに更新。
uv python upgrade
全インストール済みPythonを最新パッチに更新。

uv python dir

uvが管理するPythonのインストールディレクトリを表示します。

ポイント

  • uvが管理するPythonバイナリの格納先パスを出力。
  • 環境変数UV_PYTHON_DIRで変更可能。

使用例

uv python dir
Pythonインストールディレクトリのパスを表示。
ls $(uv python dir)
インストール済みPythonバージョンを一覧表示。

uv tool run

Pythonパッケージが提供するコマンドを一時的に実行します。uvxはこのコマンドのエイリアスです。

ポイント

  • uvx <command>: uvxはuv tool runのショートカット。
  • --from <pkg>: コマンド提供元パッケージを明示。

使用例

uvx ruff check .
ruffをインストールせずにリントを実行。
uvx --from black black --check .
blackでフォーマットチェック。

uv tool install

PythonパッケージをグローバルCLIツールとしてインストールします。

ポイント

  • ツール専用の隔離環境にインストール。
  • --python <ver>: ツール用のPythonバージョンを指定。

使用例

uv tool install ruff
ruffをグローバルツールとしてインストール。
uv tool install 'httpie>=3.0'
バージョン制約付きでhttpieをインストール。

uv tool upgrade

インストール済みツールをアップグレードします。

ポイント

  • uv tool upgrade <tool>: 特定ツールを更新。
  • --all: 全ツールを一括更新。

使用例

uv tool upgrade ruff
ruffを最新バージョンに更新。
uv tool upgrade --all
全インストール済みツールを一括更新。

uv tool list

インストール済みのグローバルツールを一覧表示します。

ポイント

  • ツール名、バージョン、提供コマンドを表示。
  • --show-paths: インストールパスも表示。

使用例

uv tool list
インストール済みツール一覧を表示。
uv tool list --show-paths
パス付きでツール一覧を表示。

uv tool uninstall

インストール済みのグローバルツールを削除します。

ポイント

  • uv tool uninstall <tool>: 指定ツールを削除。
  • --all: 全ツールを一括削除。

使用例

uv tool uninstall ruff
ruffを削除。
uv tool uninstall --all
全ツールを削除。

uv tool dir

uvツールのインストールディレクトリを表示します。

ポイント

  • ツールの隔離環境とバイナリの格納先を出力。
  • --bin: バイナリリンクのディレクトリを表示。

使用例

uv tool dir
ツールインストールディレクトリのパスを表示。
uv tool dir --bin
ツールバイナリのPATHディレクトリを表示。

uv tool update-shell

シェル設定にツールバイナリのPATHを追加します。

ポイント

  • bash/zsh/fishの設定ファイルを自動更新。
  • uv tool installの後に実行を推奨。

使用例

uv tool update-shell
シェルのPATHにツールディレクトリを追加。
uv tool install ruff && uv tool update-shell
ツールインストール後にPATHを更新。

uv pip install

pip互換インターフェースでパッケージをインストールします。

ポイント

  • -r requirements.txt: 要件ファイルからインストール。
  • --system: システムPythonにインストール。

使用例

uv pip install flask
Flaskをインストール（pipの10-100倍高速）。
uv pip install -r requirements.txt
要件ファイルから一括インストール。

uv pip uninstall

pip互換インターフェースでパッケージをアンインストールします。

ポイント

  • uv pip uninstall <pkg>: 指定パッケージを削除。
  • -r requirements.txt: 要件ファイルに記載のパッケージを削除。

使用例

uv pip uninstall flask
Flaskをアンインストール。
uv pip uninstall flask sqlalchemy
複数パッケージを同時に削除。

uv pip compile

要件ファイルをロック済みのrequirements.txtにコンパイルします。

ポイント

  • -o requirements.txt: 出力ファイル名を指定。
  • --upgrade: 全パッケージを最新にして再コンパイル。

使用例

uv pip compile requirements.in -o requirements.txt
requirements.inからロック済みファイルを生成。
uv pip compile pyproject.toml -o requirements.txt
pyproject.tomlから要件ファイルを生成。

uv pip sync

ロック済みrequirements.txtに環境を完全同期します。

ポイント

  • 不要なパッケージは自動削除される。
  • 複数の要件ファイルを指定可能。

使用例

uv pip sync requirements.txt
環境をrequirements.txtに完全一致させる。
uv pip sync requirements.txt dev-requirements.txt
本番+開発依存で同期。

uv pip freeze

インストール済みパッケージをrequirements形式で出力します。

ポイント

  • バージョン固定形式（pkg==ver）で出力。
  • pip freezeと同等の出力。

使用例

uv pip freeze
インストール済みパッケージを一覧出力。
uv pip freeze > requirements.txt
requirements.txtとして保存。

uv pip list

インストール済みパッケージを一覧表示します。

ポイント

  • --format json: JSON形式で出力。
  • --outdated: 更新可能なパッケージのみ表示。

使用例

uv pip list
インストール済みパッケージを表形式で表示。
uv pip list --format json
JSON形式でパッケージ一覧を出力。

uv pip show

指定パッケージの詳細情報を表示します。

ポイント

  • バージョン、依存関係、インストール先を表示。
  • 複数パッケージを同時に指定可能。

使用例

uv pip show flask
Flaskの詳細情報を表示。
uv pip show flask sqlalchemy
複数パッケージの詳細を同時表示。

uv pip tree

インストール済みパッケージの依存関係ツリーを表示します。

ポイント

  • --depth <n>: ツリーの深さを制限。
  • --invert: 逆依存（どのパッケージが使用しているか）を表示。

使用例

uv pip tree
全パッケージの依存ツリーを表示。
uv pip tree --depth 1
直接依存のみ表示。

uv pip check

環境内のパッケージの整合性を検証します。

ポイント

  • バージョン競合や欠落した依存を検出。
  • CIパイプラインでの品質チェックに最適。

使用例

uv pip check
環境の整合性をチェック。
uv pip sync requirements.txt && uv pip check
同期後に整合性を検証。

uv cache clean

キャッシュデータを削除します。

ポイント

  • uv cache clean: 全キャッシュを削除。
  • uv cache clean <pkg>: 特定パッケージのキャッシュのみ削除。

使用例

uv cache clean
uvの全キャッシュを削除。
uv cache clean flask
flaskのキャッシュのみ削除。

uv cache prune

使用されていないキャッシュエントリを削除します。

ポイント

  • 古い・未使用のキャッシュのみ選択的に削除。
  • cleanよりディスク容量を節約しつつキャッシュを維持。

使用例

uv cache prune
未使用キャッシュを選択的に削除。
uv cache prune && uv cache dir
プルーニング後にキャッシュディレクトリを確認。

uv cache dir

キャッシュディレクトリのパスを表示します。

ポイント

  • 環境変数UV_CACHE_DIRで変更可能。
  • デフォルトはOS標準のキャッシュディレクトリ。

使用例

uv cache dir
キャッシュディレクトリのパスを表示。
du -sh $(uv cache dir)
キャッシュサイズを確認。

uv self update

uv自体を最新バージョンに更新します。

ポイント

  • uv self update: 最新の安定版に更新。
  • uv self update <ver>: 指定バージョンに更新。

使用例

uv self update
uvを最新バージョンに更新。
uv self update 0.7.0
uvをバージョン0.7.0に更新。

uv auth login

パッケージレジストリに認証情報を登録します。

ポイント

  • uv auth login <url>: 指定レジストリにログイン。
  • --token <token>: トークンを直接指定。

使用例

uv auth login https://pypi.org
PyPIにログイン。
uv auth login https://private.registry.com --token $TOKEN
プライベートレジストリにトークンでログイン。

uv auth logout

保存済みの認証情報を削除します。

ポイント

  • uv auth logout <url>: 指定レジストリの認証を削除。
  • 認証情報はOSのキーチェーンから削除。

使用例

uv auth logout https://pypi.org
PyPIの認証情報を削除。
uv auth logout https://private.registry.com
プライベートレジストリの認証を削除。

uv generate-shell-completion

シェル補完スクリプトを生成します。

ポイント

  • bash/zsh/fish/powershellに対応。
  • 生成したスクリプトをシェル設定に追加して使用。

使用例

uv generate-shell-completion zsh > ~/.zfunc/_uv
zsh用の補完スクリプトを生成。
uv generate-shell-completion bash >> ~/.bashrc
bash用の補完をbashrcに追加。

uv run --with <package> <script.py>

依存パッケージを一時追加してスクリプトを即座に実行するワークフロー。

ポイント

  • --with: プロジェクトに追加せず一時的に使用。
  • 複数の--withで複数パッケージを指定可能。

使用例

uv run --with requests python fetch.py
requestsを一時追加してスクリプトを実行。
uv run --with pandas --with matplotlib python analyze.py
pandas+matplotlibで分析スクリプトを実行。

uv pip compile requirements.in -o requirements.txt

pip-toolsからuvへ移行するワークフロー。

ポイント

  • pip-compile互換のuv pip compileで移行。
  • 既存のrequirements.inをそのまま使用可能。

使用例

uv pip compile requirements.in -o requirements.txt
pip-compileの代替としてuvでコンパイル。
uv pip sync requirements.txt
pip-syncの代替としてuvで同期。

uv sync --frozen --no-dev

CI/CDパイプラインでの高速インストールワークフロー。

ポイント

  • --frozen: ロックファイルを変更せずCI安定性を確保。
  • --no-dev: 本番依存のみでビルド時間短縮。

使用例

uv sync --frozen --no-dev
CI向けに本番依存のみ高速インストール。
uv sync --frozen && uv run pytest
依存同期後にテストを実行。

uv run --python 3.12 pytest

複数のPythonバージョンでテストを実行するワークフロー。

ポイント

  • --python: 実行ごとにPythonバージョンを切り替え。
  • tox/noxの代替として使用可能。

使用例

uv run --python 3.11 pytest
Python 3.11でテスト実行。
uv run --python 3.12 pytest && uv run --python 3.13 pytest
3.12と3.13でテストを連続実行。

uvx ruff check .

uvxでグローバルツールをインストールなしで即座に実行。

ポイント

  • npx的な使い方でPythonツールを実行。
  • 最新バージョンが自動的に使用される。

使用例

uvx ruff check .
ruffでリント実行（インストール不要）。
uvx black --check .
blackでフォーマットチェック。

uv export --format requirements-txt > requirements.txt

Dockerイメージビルド用にrequirements.txtをエクスポート。

ポイント

  • uvプロジェクトからDocker互換の要件ファイルを生成。
  • マルチステージビルドと組み合わせて最適化。

使用例

uv export --format requirements-txt > requirements.txt
Docker用にrequirements.txtを生成。
uv export --format requirements-txt --no-dev > requirements.txt
本番依存のみエクスポート。

uv コマンド一覧について

uvはAstral社が開発した超高速Pythonパッケージマネージャーです。Rustで書かれており、pip/pip-tools/poetry/pyenvの機能を1つのツールに統合し、10-100倍の高速化を実現しています。このリファレンスではuvの全コマンドをカテゴリ別に整理し、実践的な使用例とともに紹介しています。

主な機能

  • uvの全49コマンドをカテゴリ別に分類
  • 各コマンドのオプションと実行例を掲載
  • キーワード検索でコマンド・オプション・使用例を横断検索
  • ワンクリックでコマンドをコピー
  • pip/poetryからの移行ワークフローを掲載

こんなときに便利

  • uvのコマンドを素早く確認したいとき
  • pip/poetryからuvに移行したいとき
  • CIパイプラインでuvを使いたいとき
  • Pythonバージョン管理をuvに統合したいとき
  • Docker環境でuvを活用したいとき

よくある質問

uvとpipの違いは何ですか？

uvはRustで書かれた高速なパッケージマネージャーで、pipの10-100倍高速です。pip互換のインターフェース（uv pip install等）を提供しつつ、プロジェクト管理（uv add/sync）やPythonバージョン管理（uv python install）も統合しています。

uvでpip/poetry/pyenvを全て置き換えられますか？

はい。uvはパッケージインストール（pip代替）、依存関係ロック（pip-tools/poetry代替）、Pythonバージョン管理（pyenv代替）、ツール実行（pipx代替）を1つのツールで提供します。

既存のrequirements.txtやpyproject.tomlはそのまま使えますか？

はい。uv pip installはrequirements.txtをそのまま読み込めます。pyproject.tomlもuv initで作成した形式に加え、既存のPEP 621準拠のファイルに対応しています。

uvxとnpxの違いは何ですか？

uvxはPython版のnpxに相当します。パッケージをグローバルインストールせずに一時的にコマンドを実行できます。例えばuvx ruff check .でruffをインストールなしで実行できます。

CI/CDでuvを使うメリットは？

uvの高速なインストール速度により、CIのセットアップ時間を大幅に短縮できます。uv sync --frozen --no-devで再現性の高い本番環境を高速に構築できます。

関連ツール

mise コマンド一覧asdfコマンド一覧Dockerコマンド一覧Gitコマンド一覧