uv-tool-management

UV ツール管理

UV（pipx の代替）を使用して、グローバルな Python ツールをインストール、管理するためのクイックリファレンスです。

このスキルを使用する場面

次の場合にこのスキルを使用します…	次の場合は、目的に特化した関連スキルを使用します…
uv tool install を使用してグローバル CLI ツール（ruff、black、ipython）を pipx の代わりにインストールする	venv 内でプロジェクトスクリプトを実行する — uv-run を使用
インストールせずに uvx tool で CLI を一度だけ実行する	ツールをプロジェクトの開発依存関係として追加する — uv-project-management を使用
グローバルにインストールしたツールの一覧表示、アップグレード、アンインストールを行う	ツールが実行される Python のバージョンを固定する — uv-python-versions を使用

このスキルが適用される場面

• コマンドラインツールをグローバルにインストールする（pipx のように）
• ツールのインストールと更新を管理する
• インストールせずにツールを一時的に実行する
• インストール済みツールを一覧表示、削除する
• ツールのバージョンを管理する

クイックリファレンス

ツールのインストール

# Install tool globally
uv tool install ruff
uv tool install black
uv tool install pytest

# Install specific version
uv tool install [email protected]
uv tool install 'pytest>=7.0'

# Install from Git
uv tool install git+https://github.com/astral-sh/ruff

# Install with extras
uv tool install 'mkdocs[i18n]'
uv tool install 'fastapi[all]'

ツールの実行

# Run without installing (ephemeral)
uvx pycowsay "hello world"
uvx ruff check .
uvx black --check .

# uvx is alias for:
uv tool run pycowsay "hello world"

# Run with specific version
uvx [email protected] check .

# Run from Git
uvx git+https://github.com/user/tool script.py

ツールの管理

# List installed tools
uv tool list

# Update tool
uv tool install ruff --reinstall
uv tool upgrade ruff

# Remove tool
uv tool uninstall ruff

# Remove all tools
uv tool uninstall --all

ツール情報

# Check tool version
ruff --version

# List tool binaries
uv tool list --verbose

# Show tool location
which ruff
# ~/.local/bin/ruff (Linux)
# ~/Library/Application Support/uv/bin/ruff (macOS)

uvx と uv tool run の違い

次のコマンドは同等です。

uvx ruff check .
uv tool run ruff check .

uvx は、ツールを一時的に実行するための便利な省略形です。

インストール先

ツールディレクトリ

# Linux
~/.local/share/uv/tools/

# macOS
~/Library/Application Support/uv/tools/

# Windows
%LOCALAPPDATA%\uv\tools\

バイナリ（実行ファイル）

# Linux
~/.local/bin/

# macOS
~/Library/Application Support/uv/bin/

# Windows
%LOCALAPPDATA%\uv\bin\

PATH に追加：

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

一般的なツール

# Code quality
uv tool install ruff
uv tool install black
uv tool install ty

# Documentation
uv tool install mkdocs
uv tool install sphinx

# Testing
uv tool install pytest
uv tool install tox

# Build tools
uv tool install build
uv tool install twine

# Utilities
uv tool install httpie
uv tool install pipx
uv tool install cookiecutter

UV ツールとプロジェクトの依存関係

次の場合は uv tool を使用します：

• コマンドラインアプリケーション
• グローバルな開発ツール
• 複数のプロジェクトで使用するユーティリティ

次の場合は uv add を使用します：

• プロジェクト固有の依存関係
• コード内でインポートするライブラリ
• 特定のプロジェクトの開発依存関係

# Global tool (any project)
uv tool install ruff

# Project dependency (one project)
uv add --dev ruff

ツールの分離

各ツールには専用の仮想環境が割り当てられます。

# Each tool is isolated
~/.local/share/uv/tools/
├── ruff/           # Isolated environment for ruff
├── black/          # Isolated environment for black
└── pytest/         # Isolated environment for pytest

# No dependency conflicts between tools

一般的なワークフロー

開発ツールのセットアップ

# Install common development tools globally
uv tool install ruff
uv tool install ty
uv tool install pytest
uv tool install ipython

# Now available in any project
ruff check .
ty check src/
pytest
ipython

ツールの一時的な使用

# Run without installing
uvx pycowsay "Temporary tool!"
uvx httpie https://api.github.com

# No cleanup needed

pipx の置き換え

# Old (pipx)
pipx install black
pipx run pycowsay "hello"

# New (uv)
uv tool install black
uvx pycowsay "hello"

主な機能

• 高速：pipx より 10～100 倍高速
• 分離：ツールごとに個別の環境
• 一時実行：インストールせずにツールを実行
• バージョン管理：ツールのバージョンを固定
• Git サポート：リポジトリからインストール

関連項目

• uv-project-management - プロジェクト固有の依存関係
• uv-python-versions - ツール用の Python バージョン
• python-code-quality - ruff、ty、black の使用

参考資料

• 公式ドキュメント：https://docs.astral.sh/uv/guides/tools/
• ツールディレクトリ：uv cache dir を使用してキャッシュの場所を確認します
• 詳細ガイド：このスキルディレクトリ内の REFERENCE.md を参照してください