UV Tool Management
Quick reference for installing and managing global Python tools with UV (pipx alternative).
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 dependenciesuv-python-versions- Python versions for toolspython-code-quality- Using ruff, ty, black
References
- Official docs: https://docs.astral.sh/uv/guides/tools/
- Tool directory: Use
uv cache dirto find cache location - Detailed guide: See REFERENCE.md in this skill directory
Converted and distributed by TomeVault — claim your Tome and manage your conversions.