Toolsツール

Tools are Python packages that provide command-line interfaces.ツールはコマンドラインインターフェースを提供するPythonパッケージです。

Note注意

See the tools guide for an introduction to working with the tools interface — this document discusses details of tool management.ツールガイドを参照して、ツールインターフェースの使い方についての紹介を確認してください。この文書ではツール管理の詳細について説明します。

The `uv tool` interface`uv tool`インターフェース

uv includes a dedicated interface for interacting with tools. Tools can be invoked without installation using uv tool run, in which case their dependencies are installed in a temporary virtual environment isolated from the current project.uvにはツールと対話するための専用インターフェースがあります。ツールは、uv tool runを使用してインストールせずに呼び出すことができ、その場合、依存関係は現在のプロジェクトから隔離された一時的な仮想環境にインストールされます。

Because it is very common to run tools without installing them, a uvx alias is provided for uv tool run — the two commands are exactly equivalent. For brevity, the documentation will mostly refer to uvx instead of uv tool run.ツールをインストールせずに実行することが非常に一般的であるため、uv tool runのためにuvxエイリアスが提供されています — これらの2つのコマンドは完全に同等です。簡潔さのために、文書では主にuvxを使用し、uv tool runには言及しません。

Tools can also be installed with uv tool install, in which case their executables are available on the PATH — an isolated virtual environment is still used, but it is not removed when the command completes.ツールはuv tool installを使用してインストールすることもでき、その場合、実行可能ファイルはPATH上で利用可能です — 隔離された仮想環境は引き続き使用されますが、コマンドが完了しても削除されません。

Execution vs installation実行とインストール

In most cases, executing a tool with uvx is more appropriate than installing the tool. Installing the tool is useful if you need the tool to be available to other programs on your system, e.g., if some script you do not control requires the tool, or if you are in a Docker image and want to make the tool available to users.ほとんどの場合、uvxでツールを実行する方が、ツールをインストールするよりも適切です。ツールをインストールすることは、システム上の他のプログラムでツールを利用可能にする必要がある場合に便利です。例えば、あなたが制御していないスクリプトがそのツールを必要とする場合や、Dockerイメージ内でツールをユーザーに提供したい場合です。

Tool environmentsツール環境

When running a tool with uvx, a virtual environment is stored in the uv cache directory and is treated as disposable, i.e., if you run uv cache clean the environment will be deleted. The environment is only cached to reduce the overhead of repeated invocations. If the environment is removed, a new one will be created automatically.ツールを uvx で実行すると、仮想環境は uv キャッシュディレクトリに保存され、使い捨てとして扱われます。つまり、uv cache clean を実行すると環境は削除されます。この環境は、繰り返しの呼び出しのオーバーヘッドを減らすためにキャッシュされます。環境が削除されると、新しい環境が自動的に作成されます。

When installing a tool with uv tool install, a virtual environment is created in the uv tools directory. The environment will not be removed unless the tool is uninstalled. If the environment is manually deleted, the tool will fail to run.ツールを uv tool install でインストールすると、仮想環境が uv tools directory に作成されます。この環境は、ツールがアンインストールされない限り削除されません。環境が手動で削除されると、ツールは実行できなくなります。

Important重要

Tool environments are not intended to be mutated directly. It is strongly recommended never to mutate a tool environment manually, e.g., with a pip operation.ツール環境は 直接変更することを意図していません。ツール環境を手動で変更することは強く推奨されません。例えば、pip 操作を使用して変更することは避けてください。

Tool versionsツールのバージョン

Unless a specific version is requested, uv tool install will install the latest available of the requested tool. uvx will use the latest available version of the requested tool on the first invocation. After that, uvx will use the cached version of the tool unless a different version is requested, the cache is pruned, or the cache is refreshed.特定のバージョンが要求されない限り、uv tool install は要求されたツールの最新の利用可能なバージョンをインストールします。uvx は、要求されたツールの最新の利用可能なバージョンを 最初の呼び出し時に 使用します。その後、uvx は、異なるバージョンが要求されるか、キャッシュが整理されるか、キャッシュが更新されない限り、キャッシュされたバージョンを使用します。

For example, to run a specific version of Ruff:例えば、Ruffの特定のバージョンを実行するには:

$ uvx ruff@0.6.0 --version
ruff 0.6.0

A subsequent invocation of uvx will use the latest, not the cached, version.次の uvx の呼び出しでは、キャッシュされたバージョンではなく最新のバージョンが使用されます。

$ uvx ruff --version
ruff 0.6.2

But, if a new version of Ruff was released, it would not be used unless the cache was refreshed.しかし、Ruffの新しいバージョンがリリースされた場合、キャッシュが更新されない限り、それは使用されません。

To request the latest version of Ruff and refresh the cache, use the @latest suffix:Ruffの最新バージョンを要求し、キャッシュを更新するには、@latest サフィックスを使用します:

$ uvx ruff@latest --version
0.6.2

Once a tool is installed with uv tool install, uvx will use the installed version by default.ツールが uv tool install でインストールされると、uvx はデフォルトでインストールされたバージョンを使用します。

For example, after installing an older version of Ruff:例えば、古いバージョンのRuffをインストールした後：

$ uv tool install ruff==0.5.0

The version of ruff and uvx ruff is the same:ruffとuvx ruffのバージョンは同じです：

$ ruff --version
ruff 0.5.0
$ uvx ruff --version
ruff 0.5.0

However, you can ignore the installed version by requesting the latest version explicitly, e.g.:ただし、最新バージョンを明示的に要求することでインストールされたバージョンを無視することができます。例：

$ uvx ruff@latest --version
0.6.2

Or, by using the --isolated flag, which will avoid refreshing the cache but ignore the installed version:または、--isolatedフラグを使用することで、キャッシュを更新せずにインストールされたバージョンを無視します：

$ uvx --isolated ruff --version
0.6.2

uv tool install will also respect the {package}@{version} and {package}@latest specifiers, as in:uv tool installは、{package}@{version}および{package}@latestの指定子も尊重します。例：

$ uv tool install ruff@latest
$ uv tool install ruff@0.6.0

Upgrading toolsツールのアップグレード

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操作で完全に再作成できます。

To upgrade all packages in a tool environmentツール環境内のすべてのパッケージをアップグレードするには

$ uv tool upgrade black

To upgrade a single package in a tool environment:ツール環境内の単一のパッケージをアップグレードするには：

$ uv tool upgrade black --upgrade-package click

Tool upgrades will respect the version constraints provided when installing the tool. For example, uv tool install black >=23,<24 followed by uv tool upgrade black will upgrade Black to the latest version in the range >=23,<24.ツールのアップグレードは、ツールをインストールする際に提供されたバージョン制約を尊重します。例えば、uv tool install black >=23,<24の後にuv tool upgrade blackを実行すると、Blackは範囲>=23,<24内の最新バージョンにアップグレードされます。

To instead replace the version constraints, reinstall the tool with uv tool install:バージョン制約を置き換える代わりに、uv tool installを使用してツールを再インストールします:

$ uv tool install black>=24

Similarly, tool upgrades will retain the settings provided when installing the tool. For example, uv tool install black --prerelease allow followed by uv tool upgrade black will retain the --prerelease allow setting.同様に、ツールのアップグレードは、ツールをインストールする際に提供された設定を保持します。例えば、 uv tool install black --prerelease allowの後にuv tool upgrade blackを実行すると、 --prerelease allowの設定が保持されます。

Note注意

Tool upgrades will reinstall the tool executables, even if they have not changed.ツールのアップグレードは、ツールの実行ファイルを再インストールします。たとえそれらが変更されていなくても。

To reinstall packages during upgrade, use the --reinstall and --reinstall-package options.アップグレード中にパッケージを再インストールするには、--reinstallおよび--reinstall-packageオプションを使用します。

To reinstall all packages in a tool environmentツール環境内のすべてのパッケージを再インストールするには

$ uv tool upgrade black --reinstall

To reinstall a single package in a tool environment:ツール環境内の単一のパッケージを再インストールするには:

$ uv tool upgrade black --reinstall-package click

Including additional dependencies追加の依存関係を含める

Additional packages can be included during tool execution:追加のパッケージはツールの実行中に含めることができます:

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

And, during tool installation:また、ツールのインストール中にも:

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

The --with option can be provided multiple times to include additional packages.--withオプションは、追加のパッケージを含めるために複数回提供できます。

The --with option supports package specifications, so a specific version can be requested:--with オプションはパッケージ仕様をサポートしているため、特定のバージョンを要求できます:

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

The -w shorthand can be used in place of the --with option:-w 短縮形は --with オプションの代わりに使用できます:

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

If the requested version conflicts with the requirements of the tool package, package resolution will fail and the command will error.要求されたバージョンがツールパッケージの要件と衝突する場合、パッケージの解決は失敗し、コマンドはエラーになります。

Installing executables from additional packages追加パッケージからの実行可能ファイルのインストール

When installing a tool, you may want to include executables from additional packages in the same tool environment. This is useful when you have related tools that work together or when you want to install multiple executables that share dependencies.ツールをインストールする際、同じツール環境に追加パッケージからの実行可能ファイルを含めたい場合があります。これは、関連するツールが一緒に動作する場合や、依存関係を共有する複数の実行可能ファイルをインストールしたい場合に便利です。

The --with-executables-from option allows you to specify additional packages whose executables should be installed alongside the main tool:--with-executables-from オプションを使用すると、メインツールと一緒にインストールすべき追加パッケージを指定できます:

$ uv tool install --with-executables-from <package1>,<package2> <tool-package>

For example, to install Ansible along with executables from ansible-core and ansible-lint:例えば、ansible-core と ansible-lint からの実行可能ファイルと一緒に Ansible をインストールするには:

$ uv tool install --with-executables-from ansible-core,ansible-lint ansible

This will install all executables from the ansible, ansible-core, and ansible-lint packages into the same tool environment, making them all available on the PATH.これにより、ansible、ansible-core、および ansible-lint パッケージからのすべての実行可能ファイルが同じツール環境にインストールされ、すべてが PATH で利用可能になります。

The --with-executables-from option can be combined with other installation options:--with-executables-from オプションは他のインストールオプションと組み合わせることができます:

$ uv tool install --with-executables-from ansible-core --with mkdocs-material ansible

Note that --with-executables-from differs from --with in that:--with-executables-from は --with と異なる点に注意してください:

--with includes additional packages as dependencies but does not install their executables--with は追加のパッケージを依存関係として含みますが、それらの実行可能ファイルはインストールしません。
--with-executables-from includes both the packages as dependencies and installs their executables--with-executables-from はパッケージを依存関係として含み、実行可能ファイルもインストールします。

Python versionsPythonのバージョン

Each tool environment is linked to a specific Python version. This uses the same Python version discovery logic as other virtual environments created by uv, but will ignore non-global Python version requests like .python-version files and the requires-python value from a pyproject.toml.各ツール環境は特定のPythonバージョンにリンクされています。これは、uvによって作成された他の仮想環境と同じPythonバージョンの発見ロジックを使用しますが、.python-versionファイルやpyproject.tomlのrequires-python値のような非グローバルなPythonバージョンリクエストは無視します。

The --python option can be used to request a specific version. See the Python version documentation for more details.--python オプションを使用して特定のバージョンをリクエストできます。詳細については、Pythonバージョンのドキュメントを参照してください。

If the Python version used by a tool is uninstalled, the tool environment will be broken and the tool may be unusable.ツールで使用されるPythonバージョンがアンインストールされている場合、ツール環境は壊れ、ツールが使用できなくなる可能性があります。

Tool executablesツールの実行可能ファイル

Tool executables include all console entry points, script entry points, and binary scripts provided by a Python package. Tool executables are symlinked into the executable directory on Unix and copied on Windows.ツールの実行可能ファイルには、すべてのコンソールエントリポイント、スクリプトエントリポイント、およびPythonパッケージによって提供されるバイナリスクリプトが含まれます。ツールの実行可能ファイルは、Unixでは実行可能ディレクトリにシンボリックリンクされ、Windowsではコピーされます。

Note注意

Executables provided by dependencies of tool packages are not installed.ツールパッケージの依存関係によって提供される実行可能ファイルはインストールされません。

The executable directory must be in the PATH variable for tool executables to be available from the shell. If it is not in the PATH, a warning will be displayed. The uv tool update-shell command can be used to add the executable directory to the PATH in common shell configuration files.実行可能ディレクトリは、ツールの実行可能ファイルがシェルから利用可能であるためにPATH変数に含まれている必要があります。PATHに含まれていない場合、警告が表示されます。uv tool update-shellコマンドを使用して、一般的なシェル設定ファイルに実行可能ディレクトリをPATHに追加できます。

Overwriting executables実行可能ファイルの上書き

Installation of tools will not overwrite executables in the executable directory that were not previously installed by uv. For example, if pipx has been used to install a tool, uv tool install will fail. The --force flag can be used to override this behavior.ツールのインストールは、以前にuvによってインストールされていない実行可能ファイルディレクトリ内の実行可能ファイルを上書きしません。たとえば、pipxを使用してツールをインストールした場合、uv tool installは失敗します。--forceフラグを使用してこの動作を上書きすることができます。

Relationship to `uv runuv run`との関係

The invocation uv tool run <name> (or uvx <name>) is nearly equivalent to:uv tool run <name>（またはuvx <name>）の呼び出しは、ほぼ次のように等価です：

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

However, there are a couple notable differences when using uv's tool interface:ただし、uvのツールインターフェースを使用する際にはいくつかの顕著な違いがあります：

The --with option is not needed — the required package is inferred from the command name.--withオプションは必要ありません — 必要なパッケージはコマンド名から推測されます。
The temporary environment is cached in a dedicated location.一時環境は専用の場所にキャッシュされます。
The --no-project flag is not needed — tools are always run isolated from the project.--no-projectフラグは必要ありません — ツールは常にプロジェクトから隔離されて実行されます。
If a tool is already installed, uv tool run will use the installed version but uv run will not.ツールがすでにインストールされている場合、uv tool runはインストールされたバージョンを使用しますが、uv runは使用しません。

If the tool should not be isolated from the project, e.g., when running pytest or mypy, then uv run should be used instead of uv tool run.ツールがプロジェクトから隔離されるべきでない場合、たとえばpytestやmypyを実行する際には、uv tool runの代わりにuv runを使用するべきです。