uv-tool-management

created	"2025-12-16T00:00:00.000Z"
modified	"2026-05-09T00:00:00.000Z"
reviewed	"2026-04-25T00:00:00.000Z"
name	uv-tool-management
description	Install and manage global Python CLI tools with uv (pipx alternative). Use when the user mentions uv tool, uvx, installing CLI tools globally, or pipx replacement.
user-invocable	false
allowed-tools	Bash, Read, Grep, Glob

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 ruff@0.1.0
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 ruff@0.1.0 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