uv-package-manager

UV Package Manager Skill

When to Activate

Activate this skill when:

• Creating new Python projects
• Adding or removing dependencies
• Running Python scripts or tools
• Managing virtual environments
• Setting up Python version management

Why UV?

• 10-100x faster than pip (Rust implementation)
• Unified tool - replaces pip, pip-tools, poetry, pyenv, virtualenv
• Reliable - lock files for reproducible builds
• Modern - built for current Python workflows

Quick Commands

# Project Management
uv init                      # Create new project
uv init --package my-lib     # Create installable package

# Dependencies
uv add requests              # Add dependency
uv add --dev pytest          # Add dev dependency
uv remove package-name       # Remove dependency

# Running Code
uv run script.py             # Run Python script
uv run pytest                # Run installed tool
uv run python -m module      # Run module

# Environment
uv sync                      # Sync dependencies
uv sync --frozen             # Sync without updating lock
uv lock                      # Update lock file
uv python install 3.12       # Install Python version

Creating Projects

# Standard project
uv init my-project
cd my-project

# Package project (for libraries)
uv init --package my-library

# Specify Python version
uv init --python 3.11

Created Structure

my-project/
├── .python-version    # Python version
├── pyproject.toml     # Project config
├── .venv/             # Virtual environment (auto-created)
└── hello.py           # Sample script

Adding Dependencies

# Basic add
uv add requests fastapi uvicorn

# With version constraints
uv add "django>=4.2,<5.0"
uv add "requests==2.31.0"
uv add "fastapi[all]"

# Dev dependencies
uv add --dev pytest black ruff mypy

# From git
uv add --git https://github.com/user/repo --branch develop

Running Scripts

# Run Python script
uv run script.py

# Run with arguments
uv run script.py --input data.csv

# Run dev tools
uv run pytest tests/ -v
uv run black .
uv run ruff check .

# Run with temporary dependency
uv run --with httpx fetch_data.py

# Start Python REPL
uv run python

Virtual Environment

UV automatically manages virtual environments:

# Created automatically on first use
uv sync          # First sync
uv add package   # First package add
uv run script.py # First run

# Manual creation
uv venv
uv venv --python 3.11

# Manual activation (rarely needed)
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

Lock Files

# Generate/update lock file
uv lock

# Sync from lock (normal)
uv sync

# Sync without updating (CI/CD)
uv sync --frozen

# Update specific package
uv lock --upgrade-package requests

# ALWAYS commit these files:
# - pyproject.toml
# - uv.lock
# - .python-version

Python Version Management

# List available versions
uv python list

# Install specific version
uv python install 3.12

# Set project version
echo "3.12" > .python-version

Migration from pip

# Import requirements.txt
uv init my-project
cd my-project
uv add -r requirements.txt

# Import dev requirements
uv add --dev -r requirements-dev.txt

Common pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.100.0",
    "uvicorn>=0.20.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
]

Best Practices

DO ✅

• Commit uv.lock and .python-version
• Use semantic versioning for dependencies
• Use --dev for development tools
• Use uv run instead of manual activation
• Use --frozen in CI/CD

DON'T ❌

• Commit .venv/ directory
• Use * for version constraints
• Mix pip and uv in same project
• Skip lock file updates after changes

Troubleshooting

# Clear cache
uv cache clean

# Verbose mode for debugging
uv --verbose add package

# Regenerate lock
uv lock
uv sync

Related Resources

See AgentUsage/uv_usage.md for complete documentation including:

• Docker integration patterns
• Workspace support for monorepos
• CI/CD configuration
• Detailed migration guides