Zenn
🌅

初めてのuv入門｜uvコマンドガイド：uv Tools編

に公開
Python
uv
tech

知識は武器とかけまして、レゴブロックと解く、その心は――
今日もKnowledge Oasisへようこそ
案内人はkoふみです
本日のテーマは『uv コマンドガイド Tools編』

はじめに

uvはPythonパッケージマネージャ兼タスクランナーとして、プロジェクトの依存管理やスクリプト実行だけでなく、外部ツールの実行やインストール機能も提供します。uvを使えば、依存関係をシームレスに扱いながら、例えばコードフォーマッタやテストランナーなどの外部ツールを一時環境で実行したり、ユーザー環境に永続的にインストールしてPATHに追加したりできます。この記事では、uvのツールインターフェースに関する主要コマンド（uvx、uv tool run、uv tool install、uv tool uninstall、uv tool list、uv tool update-shell、uv tool upgrade、uv tool dir）について、それぞれの概要、使い方、主なオプション、ポイントを解説します。

対象読者

  • Pythonプロジェクトの中で外部ツール（linters、フォーマッタ、ビルドツールなど）を使いたいエンジニア・開発者
  • uvを使ってツールの一時実行やユーザー環境への永続インストールを学びたい方
  • シェルのPATH設定やツールのバージョン管理をuv上で完結させたい方

uvx: ツールを一時環境で実行

概要

uvx は uv tool run のエイリアスであり、コマンドを仮想環境にインストールせずに一時的かつ隔離された環境で実行するコマンドです。ツールはキャッシュに保存された専用の仮想環境から実行されるため、プロジェクト環境への影響を与えずにツールを利用できます。

使い方

uvx <ツール名> \[引数...]
# 例: uvx ruff
# 例: uvx pycowsay hello from uv
  • バージョンを指定する場合：
uvx ruff\@latest check
  • パッケージとコマンド名が異なる場合は --from オプションを利用：
uvx --from httpie http
  • 追加の依存パッケージを含めたい場合は --with を使用：
uvx --with mkdocs-material mkdocs --help

主なオプション

  • @<バージョン>：特定バージョンを指定してツールを実行（例：ruff@0.3.0）。
  • --from <パッケージ名>[<extras>]：ツールのインストール元を指定（例：--from 'mypy[faster-cache]'）。
  • --with <追加パッケージ>：ツール実行時に追加で必要なパッケージをインストール。
  • --python <バージョン>：実行に使うPythonのバージョンを指定。
  • --isolated：使い捨ての一時環境をその場限りで構築して実行。

ポイント

  • 初回実行後、同じバージョンのツールがキャッシュされるため、再利用時は高速化されます。
  • キャッシュ環境をクリアするには uv cache clean を実行して削除できます。
  • プロジェクト内でプロジェクト自体をインストール済みでないと動かないツール（例：pytest や mypy）は、uv run を使ってプロジェクト環境で実行してください。

uv tool run: ツールを一時環境で実行

概要

uv tool run は、指定したツールをプロジェクトやユーザー環境に影響を与えずに一時的な仮想環境で実行するコマンドです。uvx は単なるエイリアスであり、フルコマンド名で同様に動作します。

使い方

uv tool run <ツール名> \[引数...]
# 例: uv tool run ruff check
# 例: uv tool run --from 'httpie==3.2.0' http --version
  • stdin からスクリプトを受け取って実行することも可能：
echo 'print("hello")' | uv tool run python -

主なオプション

  • --from <パッケージ@version>：実行元のツールパッケージおよびバージョンを指定。
  • --with <追加パッケージ>：ツール実行時に追加インストールする依存を指定。
  • --python <バージョン>：ツール用仮想環境のPythonバージョンを指定。
  • --isolated：使い捨ての一時環境で実行し、実行後に削除。

ポイント

  • uv run とは異なり、ツール実行環境は常にプロジェクト外で隔離されます。
  • 既に同名ツールがインストールされている場合、uv tool run はインストール済みのバージョンを優先します。
  • プロジェクトをパッケージとしてインストールする必要がある場合（例：テストフレームワークがコードを直接参照する場合）は、uv run を使ってプロジェクト環境にツールをインストールしてから実行してください。

uv tool install: ツールを永続環境にインストール

概要

uv tool install は、指定したツールパッケージをユーザー環境向けの永続的仮想環境にインストールして、実行可能ファイルをPATH上に配置するコマンドです。これにより、以降は通常のコマンドとしてツールを直接呼び出せます。

使い方

uv tool install <ツールパッケージ>
# 例: uv tool install ruff
# 例: uv tool install 'httpie>0.1.0'
# 例: uv tool install mkdocs --with mkdocs-material
  • バージョンを指定する場合は、引数として次のように @ を使います：
uv tool install ruff\@0.6.0
  • Gitソースからインストールする場合は、引数にGit URLを指定：
uv tool install git+[https://github.com/httpie/cli@master](https://github.com/httpie/cli@master)

主なオプション

  • --with <追加パッケージ>：ツール環境に追加で必要なパッケージを含める。複数回指定可能。
  • --python <バージョン>：ツール用仮想環境のPythonバージョンを指定。
  • --allow-insecure-host：不正または自己証明書のホストを信頼する場合に指定可能。
  • --build-constraints：ソース配布をビルドする際の制約ファイルを指定。

ポイント

  • インストール後、実行可能ファイルはXDG準拠ディレクトリ（例：$UV_TOOL_BIN_DIR、$HOME/.local/bin など）にリンクされます。PATHに含まれていない場合は警告が表示され、uv tool update-shell で自動追加が可能です。
  • 同じ名前の別バージョンがキャッシュにあっても、インストール済みのバージョンが優先されます。
  • ツール環境を手動で操作すると不安定になるため、pip などで直接編集しないよう注意してください。

uv tool uninstall: ツールを削除

概要

uv tool uninstall は、uv tool install で永続環境にインストールされたツールをアンインストールし、関連する実行ファイルおよび仮想環境を削除するコマンドです。

使い方

uv tool uninstall <ツール名>
# 例: uv tool uninstall ruff

主なオプション

  • （特にオプションはなく、ツール名を指定するのみです。）

ポイント

  • アンインストールすると、ツール用の仮想環境ディレクトリ（例：~/.local/share/uv/tools/<ツール名>）およびシンボリックリンク／コピーされた実行ファイルが削除されます。
  • 同名の実行ファイルが他に存在すると削除に失敗する場合があるため、事前に他のツール（pipxなど）で同じ名前のツールがインストールされていないか確認してください。

uv tool list: インストール済みツールの一覧表示

概要

uv tool list は、ユーザー環境に永続インストールされているツールの一覧を表示するコマンドです。各ツール名とバージョンが確認でき、アンインストールやアップグレードの参考情報になります。

使い方

uv tool list

主なオプション

  • （特にオプションはなく、そのまま実行すると全インストール済みツールを表示します。）

ポイント

  • インストール先ディレクトリ（デフォルトでは ~/.local/share/uv/tools/）内のサブディレクトリがツール名となり、各ディレクトリに仮想環境が格納されています。
  • バージョン情報が併記されていない場合は、uv tool dir で環境パスを確認し、--version を付与して個別に調べてみてください。

uv tool update-shell: シェル設定を更新してツール実行ファイルをPATHに追加

概要

uv tool update-shell は、ツールの実行可能ファイルディレクトリをシェル設定（例：.bashrc、.zshrc）に追加するコマンドです。これにより、新たにインストールしたツールがコマンドラインで直接使用可能になります。

使い方

uv tool update-shell

主なオプション

  • （特にオプションはなく、必要に応じて標準のuvオプションを使用できます。）

ポイント

  • 自動的にXDG標準に従ったディレクトリ（$UV_TOOL_BIN_DIR、$XDG_BIN_HOME、$HOME/.local/bin など）をシェル設定に書き込みます。
  • 書き込み後、該当ファイルを手動で開き、正しく追記されたかを確認してください。
  • PATH設定を反映するには、新しいシェルセッションを開始するか、source <設定ファイル> でリロードしましょう。

uv tool upgrade: インストール済みツールのアップグレード

概要

uv tool upgrade は、すでに永続インストールされたツールを最新バージョンまたは指定バージョンに更新するコマンドです。インストール時のバージョン制約は維持されますが、範囲を超えてアップグレードするには再度 uv tool install を実行してください。

使い方

uv tool upgrade <ツール名>
# 例: uv tool upgrade ruff
  • 複数のツールを一括アップグレードする場合：
uv tool upgrade --all
  • 依存パッケージだけ再インストールしたい場合：
uv tool upgrade <ツール名> --reinstall
  • ツール環境内の特定依存をアップグレードしたい場合：
uv tool upgrade <ツール名> --upgrade-package <依存名>

主なオプション

  • --all：インストール済みすべてのツールをアップグレード。
  • --reinstall：ツール環境にインストールされている全パッケージを再インストール。
  • --upgrade-package <依存名>：ツール環境の特定依存をアップグレード。
  • --python <バージョン>：アップグレード後に使用するPythonバージョンを指定。

ポイント

  • デフォルトでは、初回インストール時のバージョン制約を尊重し、その範囲内の最新版にアップグレードされます。制約を変更したい場合は再度 uv tool install を実行してください。
  • --all は大規模環境で依存解決に時間がかかる可能性があります。必要なツールのみ個別指定するほうが効率的な場合もあります。
  • 依存の破壊的変更が含まれる場合は、別仮想環境で事前テストするなど慎重に運用を。

uv tool dir: ツールインストールディレクトリの表示

概要

uv tool dir は、ユーザー環境にインストールされたツールが格納されている親ディレクトリのパスを出力するコマンドです。通常は ~/.local/share/uv/tools（Linux/macOS）や ~\AppData\Roaming\uv\data\tools（Windows）に配置されており、環境変数 UV_TOOL_DIR でカスタマイズ可能です。

使い方

uv tool dir

主なオプション

  • --bin：実行ファイルが置かれるディレクトリを表示。

ポイント

  • デフォルトでは ~/.local/share/uv/tools（Linux/macOS）や ~\AppData\Roaming\uv\data\tools（Windows） にツール環境が作成されますが、UV_TOOL_DIR を設定すると別ディレクトリへ変更できます。
  • 表示されたディレクトリを参照し、個別ツール環境（サブフォルダ）が存在するか確認できます。直接操作せず、アンインストールやアップグレードコマンドでメンテナンスしましょう。

まとめ

この記事では、uvのツールインターフェースに関する主要コマンド8つについて、以下の構成で解説しました。

  1. uvx：一時環境でツールを実行
  2. uv tool run：ツールを一時環境で実行（uvx の正式名）
  3. uv tool install：ツールをユーザーレベルの永続環境にインストール
  4. uv tool uninstall：永続環境からツールを削除
  5. uv tool list：インストール済みツールの一覧表示
  6. uv tool update-shell：実行ファイル配置ディレクトリをPATHに追加
  7. uv tool upgrade：インストール済みツールのアップグレード
  8. uv tool dir：ツールインストール先ディレクトリの表示

uvを活用することで、外部ツールの実行や管理をプロジェクト環境に影響を与えずに簡単に行えるようになります。この記事を参考に、あなたの開発ワークフローにもuvのツール機能を取り入れてみてください。

知識のひとつひとつは小さなレゴブロック
でも、組み合わせれば世界を変えるアイディアをカタチにする武器になる！

またKnowledge Oasisでお会いしましょう
案内人はkoふみでした

Discussion