Agent skill

uv

Python package and project management with uv. Extremely fast tool replacing pip, poetry, pyenv, and virtualenv. Use when installing packages, running scripts, managing environments, or working with workspaces. Triggers: "uv", "pip install", "python project", "uv.lock".

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/uv

SKILL.md

uv

uv is an extremely fast Python package and project manager written in Rust. It replaces pip, pip-tools, pipx, pyenv, virtualenv, and poetry.

When to Use uv

Always use uv for Python work, especially if you see:

  • The uv.lock file
  • uv headers in requirements* files ("This file was autogenerated by uv")

Don't use uv in projects managed by other tools:

  • Poetry projects (poetry.lock)
  • PDM projects (pdm.lock)

Workflows

Scripts

Use when: Running single Python files and standalone scripts.

bash
uv run script.py                      # Run a script
uv run --with requests script.py      # Run with additional packages
uv add --script script.py requests    # Add inline dependencies to script

Projects

Use when: There is a pyproject.toml or uv.lock

bash
uv init                   # Create new project
uv add requests           # Add dependency
uv add --dev pytest       # Add dev dependency
uv remove requests        # Remove dependency
uv sync                   # Install from lockfile
uv run <command>          # Run in project environment
uv run python -c ""       # Run Python in project environment
uv run -p 3.12 <command>  # Run with specific Python version

Tools

Use when: Running CLI tools (ruff, pytest, mypy) without installation.

bash
uvx <tool> <args>            # Run tool without installation
uvx <tool>@<version> <args>  # Run specific version
uvx ruff check .             # Example: run ruff

Important: Only use uv tool install when explicitly requested.

Pip Interface

Use when: Legacy workflows with requirements.txt, no uv.lock present.

bash
uv venv                                # Create virtual environment
uv pip install -r requirements.txt     # Install from requirements
uv pip compile requirements.in -o requirements.txt  # Compile deps
uv pip sync requirements.txt           # Sync environment
uv pip compile --universal requirements.in -o requirements.txt  # Cross-platform

Prefer uv init for new projects over pip interface.

Workspaces

Workspaces manage multiple related packages in a monorepo structure.

Configuration

toml
# Root pyproject.toml
[tool.uv.workspace]
members = ["packages/*", "apps/*"]
exclude = ["packages/legacy"]

[tool.uv.sources]
# Local package references
mylib = { workspace = true }
shared = { path = "../shared", editable = true }

# Git sources
mypackage = { git = "https://github.com/org/repo", branch = "main" }

Structure

my-workspace/
├── pyproject.toml          # Root workspace config
├── uv.lock                  # Single lockfile for all packages
├── packages/
│   ├── core/
│   │   └── pyproject.toml  # [project] with dependencies
│   └── utils/
│       └── pyproject.toml
└── apps/
    └── api/
        └── pyproject.toml

Commands

bash
uv sync                           # Sync all workspace packages
uv sync --package myapp           # Sync specific package
uv run --package myapp pytest     # Run in specific package context
uv add requests --package myapp   # Add dep to specific package
uv lock                           # Update workspace lockfile

Cross-Package Dependencies

toml
# apps/api/pyproject.toml
[project]
dependencies = ["core", "utils"]

[tool.uv.sources]
core = { workspace = true }
utils = { workspace = true }

Python Version Management

bash
uv python install 3.12           # Install Python version
uv python list --only-installed  # List installed versions
uv python pin 3.12               # Pin version for project
uv python install 3.12 --default # Set as system default

Common Patterns

Don't use pip in uv projects

bash
# ❌ Bad
uv pip install requests

# ✅ Good
uv add requests

Don't run python directly

bash
# ❌ Bad
python script.py
python -c "..."

# ✅ Good
uv run script.py
uv run python -c "..."

Don't manually manage environments

bash
# ❌ Bad
python -m venv .venv
source .venv/bin/activate

# ✅ Good
uv run <command>

Running with specific Python

bash
# ❌ Bad
python3.12 -c "..."

# ✅ Good
uvx python@3.12 -c "..."
uv run -p 3.12 <command>

Migration

From pyenv

bash
pyenv install 3.12       → uv python install 3.12
pyenv versions           → uv python list --only-installed
pyenv local 3.12         → uv python pin 3.12
pyenv global 3.12        → uv python install 3.12 --default

From pipx

bash
pipx run ruff            → uvx ruff
pipx install ruff        → uv tool install ruff
pipx upgrade ruff        → uv tool upgrade ruff
pipx list                → uv tool list

From pip/pip-tools

bash
pip install package      → uv pip install package
pip-compile req.in       → uv pip compile req.in
pip-sync req.txt         → uv pip sync req.txt
virtualenv .venv         → uv venv

Best Practices

Project Setup:

  1. Use uv init for new projects
  2. Use uv add for dependencies (not pip install)
  3. Commit uv.lock to version control
  4. Use uv sync to reproduce environments

Workspaces:

  1. Define members with glob patterns: packages/*
  2. Use workspace = true for internal dependencies
  3. Single uv.lock at root manages all packages
  4. Run commands with --package for specific contexts

Scripts:

  1. Use uv run script.py instead of python script.py
  2. Use --with for ad-hoc dependencies
  3. Use uv add --script for persistent script dependencies

Documentation

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results