laurigates/uv-tool-management

UV Tool Management

Quick reference for installing and managing global Python tools with UV (pipx alternative).

When to Use This Skill

| Use this skill when... | Use a focused sibling instead when... | |---|---| | Installing a global CLI tool (ruff, black, ipython) with uv tool install as a pipx replacement | Running a project script inside its venv — use uv-run | | Running a one-off CLI invocation via uvx tool without installing | Adding the tool as a project dev dependency — use uv-project-management | | Listing, upgrading, or uninstalling globally installed tools | Pinning the Python version a tool runs on — use uv-python-versions |

When This Skill Applies

• Installing command-line tools globally (like pipx)
• Managing tool installations and updates
• Running tools ephemerally without installation
• Listing and removing installed tools
• Tool version management

Quick Reference

Installing Tools

# 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]'

Running Tools

# 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

Managing Tools

# 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

Tool Information

# 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 vs uv tool run

These commands are equivalent:

uvx ruff check .
uv tool run ruff check .

uvx is a convenient shorthand for ephemeral tool execution.

Installation Locations

Tools Directory

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

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

# Windows
%LOCALAPPDATA%\uv\tools\

Binaries (Executables)

# Linux
~/.local/bin/

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

# Windows
%LOCALAPPDATA%\uv\bin\

Add to PATH:

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

Common Tools

# 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 Tool vs Project Dependencies

Use uv tool for:

• Command-line applications
• Global development tools
• Utilities used across projects

Use uv add for:

• Project-specific dependencies
• Libraries imported in code
• Development dependencies in specific projects

# Global tool (any project)
uv tool install ruff

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

Tool Isolation

Each tool gets its own virtual environment:

# 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

Common Workflows

Setup Development 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

One-Off Tool Usage

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

# No cleanup needed

Replace pipx

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

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

Key Features

• Fast: 10-100x faster than pipx
• Isolated: Each tool in separate environment
• Ephemeral: Run tools without installation
• Version control: Pin tool versions
• Git support: Install from repositories

See Also

• uv-project-management - Project-specific dependencies
• uv-python-versions - Python versions for tools
• python-code-quality - Using ruff, ty, black

References

• Official docs: https://docs.astral.sh/uv/guides/tools/
• Tool directory: Use uv cache dir to find cache location
• Detailed guide: See REFERENCE.md in this skill directory