Skip to content

Tools#

ツールは、コマンドラインインターフェイスを提供するPythonパッケージです。ツールは、uvxを使用してインストールせずに呼び出すことができます。この場合、ツールの依存関係は現在のプロジェクトから分離された一時的な仮想環境にインストールされます。ツールはuv tool installを使用してインストールすることもできます。この場合、ツールの実行可能ファイルはPATHで利用できます。分離された仮想環境は引き続き使用されますが、使い捨てとして扱われません。

Note

See the tools guide for an introduction to working with the tools interface — this document discusses details of tool management.

ツールインタフェースの使用方法については、tools guideを参照してください。このドキュメントでは、ツール管理の詳細について説明しています。

Tool environments#

uvxまたはuv tool runでツールを実行すると、仮想環境はuvキャッシュディレクトリに保存され、ディスポーザブルとして扱われます。環境は、呼び出しのオーバーヘッドを減らすためにキャッシュされます。

uv tool installでツールをインストールすると、uv toolsディレクトリに仮想環境が作成されます。

Tools directory#

デフォルトでは、uvツールディレクトリはtoolsという名前で、~/.local/share/uv/toolsのようにuvアプリケーションの状態ディレクトリにあります。この場所はUV_TOOL_DIR環境変数でカスタマイズできます。

ツールのインストールディレクトリのパスを表示するには、次の手順に従います。:

$ uv tool dir

ツール環境は、例えば.../tools/<name>のように、ツールパッケージと同じ名前のディレクトリに置かれます。

Mutating tool environments#

ツール環境を直接変更することは_意図されていません_。pip操作でツール環境を手動で変更しないことを強くお勧めします。

Tool environments may be upgraded via uv tool upgrade, or re-created entirely via subsequent uv tool install operations.

ツール環境は、uv tool upgradeを介してアップグレードするか、またはその後のuv tool install操作を介して完全に再作成することができます。

ツール環境のすべてのパッケージをアップグレードするには

$ uv tool upgrade black

ツール環境で1つのパッケージをアップグレードするには:

$ uv tool upgrade black --upgrade-package click

ツール環境ですべてのパッケージを再インストールするには:

$ uv tool upgrade black --reinstall

ツール環境で1つのパッケージを再インストールするには:

$ uv tool upgrade black --reinstall-package click

ツールのアップグレードでは、ツールのインストール時に指定されたバージョンの制約が考慮されます。たとえば、uv tool install black>=23,<24の後にuv tool upgrade blackを指定すると、Blackは>=23,<24の範囲の最新バージョンにアップグレードされます。

代わりにバージョン制約を置き換えるには、uv tool installでツールを再インストールします。:

$ uv tool install black>=24

同様に、ツールのアップグレードでは、ツールのインストール時に提供された設定が保持されます。たとえば、uv tool install black--prelease allowの後にuv tool upgrade blackを実行すると、--prelease allow設定が保持されます。

ツールをアップグレードすると、ツールの実行可能ファイルが変更されていない場合でも再インストールされます。

Including additional dependencies#

ツールの呼び出し中に追加パッケージを含めることができます。:

$ uvx --with <extra-package> <tool>

インストール:

$ uv tool install --with <extra-package> <tool-package>

--withオプションを複数回指定して、追加のパッケージを含めることができます。

--withオプションはパッケージ仕様をサポートしているので、特定のバージョンを要求することができます。

$ uvx --with <extra-package>==<version> <tool-package>

要求されたバージョンがツールパッケージの要件と矛盾する場合、パッケージの解決は失敗し、コマンドはエラーになります。

Tool executables#

ツール実行可能ファイルには、Pythonパッケージで提供されるすべてのコンソールエントリポイント、スクリプトエントリポイント、およびバイナリスクリプトが含まれます。ツール実行可能ファイルは、Unixではbinディレクトリにシンボリックリンクされ、Windowsではコピーされます。

The bin directory#

実行可能ファイルは、~/.local/binのようなXDG標準に従ってユーザのbinディレクトリにインストールされます。uvの他のディレクトリスキームとは異なり、XDG標準は、特にWindowsとmacOSを含むすべてのプラットフォームで使用されます。これらのプラットフォームに実行可能ファイルを配置するための明確な代替場所はありません。インストールディレクトリは、最初に使用可能な環境変数から決定されます。

  • $XDG_BIN_HOME
  • $XDG_DATA_HOME/../bin
  • $HOME/.local/bin

ツールパッケージの依存関係によって提供される実行可能ファイルがインストールされません。

The PATH#

シェルからツール実行可能ファイルを使用するには、binディレクトリがPATH変数に含まれている必要があります。PATHに含まれていない場合は、警告が表示されます。uv tool update-shellコマンドを使用して、共通シェル構成ファイルのPATHにbinディレクトリを追加できます。

Overwriting executables#

ツールのインストールでは、以前にuvによってインストールされていないbinディレクトリ内の実行可能ファイルは上書きされません。たとえば、pipxを使用してツールをインストールした場合、uv tool installは失敗します。--forceフラグを使用して、この動作を上書きできます。

Relationship to uv run#

uv tool run<name>の呼び出しは、次とほぼ同じです。

$ uv run --no-project --with <name> -- <name>

ただし、uvのツールインタフェースを使用する場合には、いくつかの顕著な違いがあります。:

  • --withオプションは必要ありません-必要なパッケージはコマンド名から推測されます。
  • 一時環境は専用の場所にキャッシュされます。
  • --no-projectフラグは必要ありません-ツールは常にプロジェクトから分離して実行されます。
  • ツールがすでにインストールされている場合、uv tool runはインストールされているバージョンを使用しますが、uv runは使用しません。
  • プロジェクトは、編集可能なインストールを使用せずに構築およびインストールされます。