Uv Tool Management

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.

laurigates b5b58e0 2 files · 17.8 KB Updated Sep 9, 2026

Coding & Dev Tools

Install

Press C to copy

$ npx skillmds@latest add laurigates/uv-tool-management

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to collection

README badge

[![SkillMD](https://skillmd.com/badge/laurigates/uv-tool-management.svg)](https://skillmd.com/skills/laurigates/uv-tool-management)

Trust & safety

Audits pending

Not yet audited · commit b5b58e0

Permissions this skill uses

Makes network calls
The instructions fetch remote URLs or call external services.

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

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

---name: uv-tool-managementdescription: 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.--- # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash uvx ruff check . uv tool run ruff check . ``` `uvx` is a convenient shorthand for ephemeral tool execution. ## Installation Locations ### Tools Directory ```bash # Linux ~/.local/share/uv/tools/ # macOS ~/Library/Application Support/uv/tools/ # Windows %LOCALAPPDATA%\uv\tools\ ``` ### Binaries (Executables) ```bash # Linux ~/.local/bin/ # macOS ~/Library/Application Support/uv/bin/ # Windows %LOCALAPPDATA%\uv\bin\ ``` **Add to PATH:** ```bash # Add to ~/.bashrc or ~/.zshrc export PATH="$HOME/.local/bin:$PATH" ``` ## Common Tools ```bash # 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 ```bash # 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: ```bash # 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 ```bash # 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 ```bash # Run without installing uvx pycowsay "Temporary tool!" uvx httpie https://api.github.com # No cleanup needed ``` ### Replace pipx ```bash # 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

laurigates/claude-plugins/tree/main/python-plugin/skills/uv-tool-management commit b5b58e0db1

Frequently asked questions

npx skillmds@latest add laurigates/uv-tool-management