初めてのuv入門｜uvコマンド一覧：全機能をサクッと俯瞰
知識は武器とかけまして、レゴブロックと解く、その心は――
今日もKnowledge Oasisへようこそ。
案内人はkoふみです。
本日のテーマは『uvコマンド一覧：全体像の俯瞰』です。
対象読者
- Pythonの依存管理や仮想環境管理を一本化したい開発者
- uvの導入を検討しており、どのようなコマンドがあるかをざっと把握したい方
uvコマンドの全体像
この章では、uv が提供するコマンドを大きく以下のカテゴリに分けて一覧化します。各コマンド名と簡潔な説明のみを示しています。
-
Python versions
Python 本体のインストールや管理を行うコマンド群 -
Scripts
単体の Python スクリプト（例：example.py）を仮想環境下で実行・管理するコマンド群 -
Projects
pyproject.tomlを用いるプロジェクト全体を作成・管理するコマンド群 -
Tools
Python パッケージインデックスに公開されている CLI ツール（例：ruffやblack）を一時実行・インストールするコマンド群 -
The pip interface
従来のvenvやpip／pipdeptree、pip-toolsを直接操作するための低レイヤーコマンド群 -
Utilities
uv 本体や環境のメンテナンス、キャッシュ管理、シェル補完などを行うコマンド群
具体的な使い方や実行例は別記事で扱うため、本記事ではコマンドの概要にとどめています。
1. Python versions
Python 本体のインストールや管理を行うコマンド群です。
-
uv python install <バージョン>
ローカルに指定バージョンの Python をインストールします。 -
uv python list
利用可能なPythonのバージョンを表示します。 -
uv python find
現在使用しているPythonのインストール先を表示します。 -
uv python pin <バージョン>
使用するPythonのバージョンを固定します。 -
uv python uninstall <バージョン>
指定のバージョンのPythonをアンインストールします。
2. Scripts
単体の Python スクリプト（例：example.py）を仮想環境下で実行・管理するコマンド群です。
-
uv run <スクリプト名>
カレントディレクトリの仮想環境を使って指定したスクリプトを実行します。 -
uv add --script <パッケージ名>
スクリプト実行用の一時環境に依存パッケージを追加します。 -
uv remove --script <パッケージ名>
スクリプト実行用一時環境から指定パッケージを削除します。
3. Projects
pyproject.toml を用いるプロジェクト全体を作成・管理するコマンド群です。
-
uv init <プロジェクト名>
新しい Python プロジェクト用フォルダとpyproject.tomlを生成し、初期化します。 -
uv add <パッケージ名>
プロジェクトの依存関係として指定パッケージを追加し、pyproject.tomlに反映します。 -
uv remove <パッケージ名>
プロジェクトの依存関係から指定パッケージを削除し、pyproject.tomlを更新します。 -
uv sync
pyproject.tomlまたはロックファイルを参照して仮想環境を構築／再構築します。 -
uv lock
pyproject.tomlの依存関係をもとにロックファイルを生成します。 -
uv run <コマンド>
プロジェクトの仮想環境内で任意のコマンドを実行します。 -
uv tree
プロジェクト依存のツリー構造を表示します。 -
uv build
pyproject.tomlの設定に従い、配布用アーカイブをdist/に出力します。 -
uv publish
ビルド済みパッケージをリモートリポジトリ（例：PyPI）へ一括でアップロードします。
4. Tools
Python パッケージインデックスに公開されている CLI ツール（例：ruff や black）を一時実行・インストールするコマンド群です。
-
uvx <ツール名>
一時環境を作成し、指定ツールをダウンロードして実行します（uv tool runのエイリアス）。 -
uv tool run <ツール名>
同上。一時環境でツールを実行します。 -
uv tool install <ツール名>
指定ツールをユーザー全体でキャッシュし、常時利用可能にします。 -
uv tool uninstall <ツール名>
グローバルキャッシュから指定ツールを削除します。 -
uv tool list
グローバルキャッシュに保存されたツール一覧を表示します。 -
uv tool update-shell
シェル設定を更新し、インストール済みツールの実行パスをシェルに追加します。 -
uv tool upgrade
すでに永続インストールされたツールのバージョンを更新します。 -
uv tool dir
ツールが格納されている親ディレクトリのパスを出力します。
5. The pip interface
従来の venv や pip／pipdeptree、pip-tools を直接操作するための低レイヤーコマンド群です。高度な制御が必要なケース向けに用意されています。
環境作成関連
-
uv venv <サブコマンド>
仮想環境を手動で作成するためのサブコマンド群。-
uv venv create仮想環境を作成。
-
パッケージ管理関連
-
uv pip install <パッケージ名>
仮想環境内にパッケージをインストールします。 -
uv pip show <パッケージ名>
インストール済みパッケージの詳細情報を表示します。 -
uv pip freeze
現在の環境にインストールされているパッケージとバージョンをrequirements.txt形式で出力します。 -
uv pip check
環境内のパッケージ依存関係に不整合がないかを検査します。 -
uv pip list
仮想環境内のパッケージを一覧表示します。 -
uv pip uninstall <パッケージ名>
環境から指定パッケージをアンインストールします。 -
uv pip tree
環境内の依存関係をツリー形式で表示します。
ロック関連
-
uv pip compile
ロックファイルを生成し、依存バージョンを固定します。 -
uv pip sync
ロックファイルに従って環境を再構築（パッケージインストール・アンインストール）します。
6. Utilities
uv 本体や環境のメンテナンス、キャッシュ管理、シェル補完などを行うコマンド群です。
-
uv cache clean
キャッシュをクリアし、すべてのエントリまたは特定のパッケージにリンクしているエントリを削除します。 -
uv cache prune
到達不可能なオブジェクトをキャッシュから削除します。 -
uv cache dir
キャッシュの格納場所を確認します。 -
uv self update
uv 自身のアップデートを行います。 -
uv self version
uv 自身のバージョンを確認します。 -
uv generate-shell-completion
bash/zsh/fish など向けの補完スクリプトを生成します。
まとめ
本記事では、uv に用意されている全コマンドをカテゴリ別に並べ、各コマンドの使い方と概要を簡潔に説明しました。
uv を使うことで、Python の依存管理や仮想環境構築、ツール実行などを一本化できるため、作業効率が向上します。
知識のひとつひとつ小さなレゴブロック
でも、組み合わせれば世界を変えるアイディアをカタチにする武器になる！
またKnowledge Oasisでお会いしましょう
案内人はkoふみでした。
Discussion