uv-python-manager

What this skill does

# uv-python-manager

UV is the modern standard for Python package and project management in 2025, delivering 10-100x speed improvements while unifying pip, virtualenv, pyenv, poetry, and pipx into a single Rust-based tool.

## When to Use This Skill

Use this skill when:
- Creating new Python projects
- Managing dependencies and lockfiles
- Setting up virtual environments
- Installing or switching Python versions
- Building or publishing packages
- Optimizing CI/CD pipelines
- Migrating from pip, poetry, or other tools
- Creating portable Python scripts
- Working with Docker containers

## Core Principles

1. **Project-first workflow**: Use `uv init` and `uv add` instead of manual configuration
2. **Lock file discipline**: Always commit `uv.lock` for reproducibility
3. **Universal execution**: Use `uv run` instead of manual environment activation
4. **Version pinning**: Use `.python-version` for team consistency
5. **Fast by default**: Leverage caching and parallel operations (8-100x faster than pip)

## Quick Start

### Installing UV

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Update UV
uv self update
```

### Creating a New Project

```bash
# Initialize project (creates pyproject.toml, .python-version, .gitignore)
uv init my-project
cd my-project

# Add dependencies
uv add requests fastapi pandas

# Add development dependencies
uv add --dev pytest ruff mypy

# Add to custom groups
uv add --group docs sphinx
uv add --group test pytest-cov

# Run code (auto-syncs environment)
uv run python main.py
uv run pytest
```

## Essential Commands Reference

### Project Lifecycle
```bash
uv init [name]              # Create new project with structure
uv add <package>            # Add dependency (updates pyproject.toml + uv.lock)
uv add --dev <package>      # Add development dependency
uv add --group <name> <pkg> # Add to custom dependency group
uv remove <package>         # Remove dependency
uv sync                     # Install/sync all dependencies
uv sync --frozen            # Sync without updating lock (CI mode)
uv sync --no-dev            # Production install (exclude dev deps)
uv run <command>            # Run command in project environment
uv build                    # Build distribution packages
uv publish                  # Publish to PyPI
```

### Python Version Management
```bash
uv python install 3.12      # Install Python version
uv python install 3.11 3.12 # Install multiple versions
uv python list              # List installed Python versions
uv python pin 3.12          # Pin project to Python version
uv python find              # Show active Python version
```

### Virtual Environments
```bash
uv venv                     # Create virtual environment (.venv/)
uv venv --python 3.12       # Create with specific Python version
uv venv my-env              # Create with custom name
```

### Lock File Management
```bash
uv lock                     # Update lockfile from pyproject.toml
uv lock --upgrade           # Upgrade all dependencies
uv lock --upgrade-package <pkg>  # Upgrade specific package
uv lock --check             # Verify lock is current (CI check)
uv export --format requirements-txt > requirements.txt  # Export format
```

### Tool Management (replaces pipx)
```bash
uvx <tool>                  # Run tool temporarily (no install)
uvx ruff check .            # Example: run ruff once
uv tool install <tool>      # Install tool globally
uv tool list                # List installed tools
uv tool uninstall <tool>    # Remove global tool
```

### Maintenance
```bash
uv cache clean              # Clean cache
uv cache dir                # Show cache location
uv self update              # Update UV itself
```

## Project Structure Best Practices

### Standard Layout
```
project/
├── .git/
├── .gitignore          # Auto-generated by uv init
├── .python-version     # Python version pin (COMMIT THIS)
├── README.md           # Setup instructions
├── pyproject.toml      # Project configuration (COMMIT THIS)
├── uv.lock             # Universal lockfile (COMMIT THIS)
├── .venv/              # Virtual environment (DO NOT COMMIT)
├── src/
│   └── package/
│       ├── __init__.py
│       └── main.py
└── tests/
    └── test_main.py
```

### pyproject.toml Structure
```toml
[project]
name = "my-app"
version = "0.1.0"
description = "Application description"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0,<3.0.0",      # Range with upper bound
    "pandas>=2.0.0",                 # Minimum version
    "fastapi[standard]>=0.115.0",   # With extras
]

[project.optional-dependencies]
plotting = ["matplotlib>=3.7.0", "seaborn>=0.12.0"]
database = ["sqlalchemy>=2.0.0", "psycopg2-binary>=2.9.0"]

[dependency-groups]
dev = ["pytest>=8.0.0", "ruff>=0.3.0", "mypy>=1.8.0"]
test = ["pytest-cov>=4.1.0", "pytest-asyncio>=0.23.0"]
docs = ["sphinx>=7.0.0", "sphinx-rtd-theme>=2.0.0"]
```

## Key Workflows

### Dependency Management

**Adding dependencies:**
```bash
# Single package
uv add requests

# Multiple packages
uv add requests pandas numpy

# With version constraints
uv add "fastapi>=0.115.0,<1.0.0"

# With extras
uv add "fastapi[standard]"

# Development dependencies
uv add --dev pytest ruff mypy

# Optional dependency groups
uv add --optional plotting matplotlib seaborn
```

**Managing versions:**
```bash
# Upgrade all dependencies
uv lock --upgrade

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

# Pin to latest compatible versions
uv add requests --upgrade
```

### Running Code

**Always use `uv run` instead of activating environments:**
```bash
# Run Python scripts
uv run python script.py
uv run python -m mymodule

# Run installed tools
uv run pytest
uv run ruff check .
uv run mypy src/

# Run with specific Python version
uv run --python 3.12 python script.py

# Pass arguments
uv run pytest tests/ -v --cov
```

**Why `uv run` is better:**
- Auto-syncs environment before running
- Works cross-platform without activation scripts
- Ensures reproducibility
- Handles environment discovery automatically

### Inline Script Dependencies (PEP 723)

Create portable single-file scripts:

```python
#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests",
#     "rich",
# ]
# ///

import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.json())
```

Run with: `uv run script.py` (automatically installs dependencies)

### Python Version Management

**Project-level pinning:**
```bash
# Pin Python version for project
uv python pin 3.12

# This creates .python-version file
# Always commit this file to git

# UV will automatically use this version
uv run python --version
```

**Installing Python versions:**
```bash
# Install specific version
uv python install 3.12

# Install multiple versions
uv python install 3.11 3.12 3.13

# List available versions
uv python list --all-versions

# List installed versions
uv python list
```

### CI/CD Integration

**GitHub Actions example:**
```yaml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up UV
        uses: astral-sh/setup-uv@v6
        with:
          version: "0.9.5"  # Pin UV version
          enable-cache: true
      
      - name: Set up Python
        run: uv python install
      
      - name: Install dependencies
        run: uv sync --frozen  # Use --frozen in CI
      
      - name: Check lock file is current
        run: uv lock --check
      
      - name: Run tests
        run: uv run pytest
      
      - name: Run linting
        run: uv run ruff check .
```

**Docker optimization:**
```dockerfile
FROM python:3.12-slim

# Install UV
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Set working directory
WORKDIR /app

# Copy dependency files
COPY pyproject.tom