Skip to main content
skill CX Codex

uv-tool-management — Claude Code skill for CLI tools

uv-tool-management is a Claude Code skill for managing global Python CLI tools with uv and running them temporarily with uvx, including as an alternative to pipx.

MIT 328 installs ★ 60 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add laurigates/claude-plugins --skill uv-tool-management -a claude-code
Open on GitHub

What uv-tool-management does

This skill covers installing tools with uv tool install, launching them on demand with uvx, and listing, upgrading, or removing installed tools. It also shows how to choose a tool version or install from a Git repository. For instance, uvx ruff check . runs a check without a permanent ruff install.

Each installed tool has a separate virtual environment, keeping tool dependencies apart. The executable directory needs to be on PATH; otherwise, commands such as ruff will not run directly. The skill also distinguishes global CLI tools from project dependencies: use uv tool install for the former and uv add for the latter.

What it helps with

  • install a Python CLI tool for use across projects
  • run a tool once without installing it
  • list installed tools and upgrade one
  • remove a single tool or all installed tools
  • pin a CLI tool version or install it from Git

Example prompts for the agent

  • Install ruff as a global CLI tool with uv.
  • Run black --check . once without keeping it installed.
  • List the tools managed by uv and upgrade pytest.

How to install uv-tool-management

1Skills CLI (Vercel)

npx skills add laurigates/claude-plugins --skill uv-tool-management -a claude-code

2Manually: put the files in place

~/.claude/skills/uv-tool-management/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/uv-tool-management/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about uv-tool-management

How do I install uv-tool-management in Claude Code?

Run npx skills add laurigates/claude-plugins --skill uv-tool-management -a claude-code. The skill file is at ~/.claude/skills/uv-tool-management/SKILL.md.

What does uv-tool-management do?

It guides you through managing global Python CLI tools with uv: installing, upgrading, removing, and running tools temporarily with uvx.

How is uv tool different from uv add?

Use uv tool install for CLI applications you want available across projects. Use uv add to add a dependency to a specific project.

Source text

SKILL.md · MIT
---
created: 2025-12-16
modified: 2026-11-14
reviewed: 2026-04-25
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(uv tool install *), Bash(uv tool list *), Bash(uv tool upgrade *), Bash(uv tool uninstall *), Bash(uvx ruff *), Bash(uvx black *), 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

```bash
# 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

```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 [email protected] 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 · MIT · laurigates/claude-plugins

Similar skills

All skills for Programming languages →

From the same set27

The whole set →
uv-run uv-run teaches your AI assistant to execute Python scripts via uv and embed dependencies with PEP 723 without manual virtual environment activation. CX Codex +1 342installs python-packaging python-packaging guides the agent through building wheels and sdists with uv, configuring pyproject.toml, and uploading packages to PyPI or Test PyPI. CX Codex +1 336installs uv-python-versions uv-python-versions is a Claude Code skill for managing CPython and PyPy with uv. Install interpreters, pin a project version, or switch versions for testing. CX Codex +1 332installs uv-advanced-dependencies uv-advanced-dependencies is a skill for managing non-standard dependency sources in uv, including GitHub repositories, editable local packages, and private indexes. It covers projects that need Git, local path, or custom index dependencies. CX Codex +1 332installs imagemagick-conversion imagemagick-conversion — a skill for converting, resizing and optimizing images via ImageMagick command-line. Useful for bulk format conversion, thumbnail generation, and large-scale image processing workflows. CX Codex +1 260installs jq-json-processing jq-json-processing — a skill for parsing, filtering and transforming JSON with jq. Extracts fields, filters arrays, reshapes objects and validates syntax. CX Codex +1 245installs python-development python-development gives your agent Python 3.10+ idioms: type hints, pattern matching, asyncio. Handy for library code and refactors. CX Codex +1 192installs generate-image The generate-image skill generates images from text prompts using Google's Gemini 3 Pro Image model on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. CX Codex +1 177installs

Project sponsors

Companies that keep this analytics open