ツール
ツールは、コマンドラインインターフェースを提供するPythonパッケージです。
Note
ツールインターフェースの使用方法については、ツールガイドを参照してください。このドキュメントでは、ツール管理の詳細について説明します。
uv toolインターフェース
uvには、ツールと対話するための専用インターフェースが含まれています。ツールはuv tool runを使用してインストールせずに呼び出すことができます。この場合、依存関係は現在のプロジェクトから隔離された一時的な仮想環境にインストールされます。
ツールをインストールせずに実行することが非常に一般的であるため、uv tool runのエイリアスとしてuvxが提供されています。これらの2つのコマンドは完全に同等です。簡潔さのために、ドキュメントでは主にuvxを指します。
ツールはuv tool installを使用してインストールすることもできます。この場合、実行可能ファイルはPATHに配置されます。隔離された仮想環境は引き続き使用されますが、コマンドが完了しても削除されません。
実行とインストールの違い
ほとんどの場合、ツールをuvxで実行する方が、ツールをインストールするよりも適しています。ツールをインストールするのは、システム上の他のプログラムでツールが利用可能である必要がある場合に便利です。例えば、制御できないスクリプトがツールを必要とする場合や、Dockerイメージ内でツールをユーザーに提供する場合です。
ツール環境
uvxでツールを実行する場合、仮想環境はuvキャッシュディレクトリに保存され、一時的なものとして扱われます。つまり、uv cache cleanを実行すると環境が削除されます。環境は繰り返しの呼び出しのオーバーヘッドを減らすためにのみキャッシュされます。環境が削除された場合、新しい環境が自動的に作成されます。
uv tool installでツールをインストールする場合、仮想環境はuvツールディレクトリに作成されます。環境はツールがアンインストールされるまで削除されません。環境が手動で削除された場合、ツールは実行に失敗します。
ツールのバージョン
特定のバージョンが要求されない限り、uv tool installは要求されたツールの最新バージョンをインストールします。uvxは最初の呼び出し時に要求されたツールの最新バージョンを使用します。その後、uvxは異なるバージョンが要求されるか、キャッシュがプルーニングされるか、キャッシュが更新されない限り、キャッシュされたバージョンを使用します。
例えば、特定のバージョンのRuffを実行するには：
その後のuvxの呼び出しは、キャッシュされたバージョンではなく最新バージョンを使用します。
ただし、新しいバージョンのRuffがリリースされた場合、それはキャッシュが更新されない限り使用されません。
Ruffの最新バージョンを要求し、キャッシュを更新するには、@latestサフィックスを使用します：
ツールがuv tool installでインストールされると、uvxはデフォルトでインストールされたバージョンを使用します。
例えば、古いバージョンのRuffをインストールした後：
ruffとuvx ruffのバージョンは同じです：
ただし、インストールされたバージョンを無視するには、最新バージョンを明示的に要求します。例：
または、--isolatedフラグを使用して、キャッシュを更新せずにインストールされたバージョンを無視します：
uv tool installも{package}@{version}および{package}@latest指定子を尊重します。例：
ツールディレクトリ
デフォルトでは、uvツールディレクトリはtoolsという名前で、uvアプリケーションステートディレクトリにあります。例：~/.local/share/uv/tools。場所はUV_TOOL_DIR環境変数でカスタマイズできます。
ツールインストールディレクトリのパスを表示するには：
ツール環境はツールパッケージと同じ名前のディレクトリに配置されます。例：.../tools/<name>。
ツール環境の変更
ツール環境は直接変更することを意図していません。ツール環境を手動でpip操作で変更することは強く推奨されません。
ツール環境はuv tool upgradeを介してアップグレードするか、後続のuv tool install操作を介して完全に再作成できます。
ツール環境内のすべてのパッケージをアップグレードするには：
ツール環境内の単一のパッケージをアップグレードするには：
ツール環境内のすべてのパッケージを再インストールするには：
ツール環境内の単一のパッケージを再インストールするには：
ツールのアップグレードは、ツールのインストール時に提供されたバージョン制約を尊重します。例えば、uv tool install black >=23,<24の後にuv tool upgrade blackを実行すると、Blackは>=23,<24の範囲内の最新バージョンにアップグレードされます。
バージョン制約を置き換えるには、uv tool installでツールを再インストールします：
同様に、ツールのアップグレードは、ツールのインストール時に提供された設定を保持します。例えば、uv tool install black --prerelease allowの後にuv tool upgrade blackを実行すると、--prerelease allow設定が保持されます。
ツールのアップグレードは、ツールの実行可能ファイルを再インストールします。たとえそれらが変更されていなくても。
追加の依存関係の含め
ツールの実行中に追加のパッケージを含めることができます：
また、ツールのインストール中にも：
--withオプションは複数回提供して追加のパッケージを含めることができます。
--withオプションはパッケージ仕様をサポートしているため、特定のバージョンを要求できます：
要求されたバージョンがツールパッケージの要件と競合する場合、パッケージの解決は失敗し、コマンドはエラーになります。
ツールの実行可能ファイル
ツールの実行可能ファイルには、Pythonパッケージが提供するすべてのコンソールエントリポイント、スクリプトエントリポイント、およびバイナリスクリプトが含まれます。ツールの実行可能ファイルはUnixではbinディレクトリにシンボリックリンクされ、Windowsではコピーされます。
binディレクトリ
実行可能ファイルはXDG標準に従ってユーザーのbinディレクトリにインストールされます。例：~/.local/bin。uvの他のディレクトリスキームとは異なり、XDG標準はすべてのプラットフォームで使用されます。特にWindowsとmacOSを含みます。これらのプラットフォームには実行可能ファイルを配置する明確な代替場所がないためです。インストールディレクトリは最初に利用可能な環境変数から決定されます：
$UV_TOOL_BIN_DIR$XDG_BIN_HOME$XDG_DATA_HOME/../bin$HOME/.local/bin
ツールパッケージの依存関係によって提供される実行可能ファイルはインストールされません。
PATH
ツールの実行可能ファイルをシェルから利用できるようにするには、binディレクトリがPATH変数に含まれている必要があります。PATHに含まれていない場合、警告が表示されます。uv tool update-shellコマンドを使用して、一般的なシェル構成ファイルにbinディレクトリを追加できます。
実行可能ファイルの上書き
ツールのインストールは、uvによって以前にインストールされていないbinディレクトリの実行可能ファイルを上書きしません。例えば、pipxを使用してツールをインストールした場合、uv tool installは失敗します。この動作を上書きするには、--forceフラグを使用できます。
uv runとの関係
uv tool run <name>（またはuvx <name>）の呼び出しは、ほぼ次のコマンドと同等です：
ただし、uvのツールインターフェースを使用する場合にはいくつかの重要な違いがあります：
--withオプションは必要ありません。必要なパッケージはコマンド名から推測されます。- 一時的な環境は専用の場所にキャッシュされます。
--no-projectフラグは必要ありません。ツールは常にプロジェクトから隔離されて実行されます。- ツールがすでにインストールされている場合、
uv tool runはインストールされたバージョンを使用しますが、uv runは使用しません。
ツールがプロジェクトから隔離されるべきでない場合、例：pytestやmypyを実行する場合、uv tool runの代わりにuv runを使用する必要があります。