---
name: uv-python-manager
description: Standardize Python development using UV - a fast, unified package and project manager. Use when creating Python projects, managing dependencies, setting up virtual environments, installing Python versions, or optimizing Python workflows. Replaces pip, virtualenv, pyenv, poetry, and pipx with a single 10-100x faster tool.
---

# 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.toml uv.lock ./

# Install dependencies with caching
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

# Copy application code
COPY . .

# Compile bytecode for faster startup
ENV UV_COMPILE_BYTECODE=1

# Run application
CMD ["uv", "run", "python", "-m", "myapp"]
```

**Multi-stage Docker build:**
```dockerfile
# Stage 1: Build
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev --no-editable

# Stage 2: Runtime
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY . .
ENV PATH="/app/.venv/bin:$PATH"
ENV UV_COMPILE_BYTECODE=1
CMD ["python", "-m", "myapp"]
```

## Migration from Existing Tools

### From pip/pip-tools
```bash
# Automated migration
uvx migrate-to-uv

# Or manual migration:
# 1. Create UV project
uv init

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

# 3. Commit new files
git add pyproject.toml uv.lock .python-version
git rm requirements.txt requirements-dev.txt
```

### From Poetry
```bash
# Automated migration
uvx migrate-to-uv

# UV reads pyproject.toml directly
# Just start using UV commands:
uv sync        # Replaces: poetry install
uv add pkg     # Replaces: poetry add pkg
uv run cmd     # Replaces: poetry run cmd
```

### From virtualenv/venv
```bash
# Old workflow:
# python -m venv .venv
# source .venv/bin/activate  # or .venv\Scripts\activate on Windows
# pip install -r requirements.txt

# New workflow:
uv init
uv add -r requirements.txt
uv run python script.py  # No activation needed
```

## Troubleshooting

### Common Issues

**Lock file out of sync:**
```bash
# Error: "lock file is out of date"
uv lock  # Regenerate lock file
```

**Python version not found:**
```bash
# Error: "Python 3.12 not found"
uv python install 3.12
```

**Dependency conflicts:**
```bash
# Check resolution
uv lock --verbose

# Try upgrading
uv lock --upgrade

# Check specific package
uv lock --upgrade-package problematic-package
```

**Cache issues:**
```bash
# Clean cache if corrupted
uv cache clean

# Show cache location
uv cache dir
```

**Import resolution issues:**
```bash
# Ensure environment is synced
uv sync

# Force reinstall
uv sync --reinstall
```

## Best Practices Checklist

- ✅ Always commit `uv.lock` and `.python-version` to version control
- ✅ Use `uv sync --frozen` in CI/CD pipelines
- ✅ Add `.venv/` to `.gitignore` and `.dockerignore`
- ✅ Pin UV version in CI for consistency
- ✅ Use `uv run` instead of manual environment activation
- ✅ Specify `requires-python` range in `pyproject.toml`
- ✅ Use dependency groups for dev tools, not optional-dependencies
- ✅ Test with `--resolution lowest` for libraries
- ✅ Enable bytecode compilation in Docker: `UV_COMPILE_BYTECODE=1`
- ✅ Use cache mounts in Docker for faster builds
- ✅ Run `uv lock --check` in CI to catch outdated lockfiles
- ✅ Leverage inline script dependencies (PEP 723) for portable tools
- ✅ Document UV setup in README for team onboarding

## Performance Impact

UV achieves dramatic speed improvements:
- **8-10x faster** than pip without caching
- **80-115x faster** with warm cache
- **Virtual environment creation:** 100ms vs 8 seconds (python -m venv)
- **Complex dependency resolution:** seconds vs minutes
- **CI/CD impact:** 30-65% faster builds

This speed enables new workflows like re-syncing environments on every command invocation without performance penalties.

## Advanced Topics

For more specialized use cases, see:
- [WORKSPACE.md](WORKSPACE.md) - Monorepo and multi-project setups
- [PUBLISHING.md](PUBLISHING.md) - Building and publishing packages
- [SCRIPTS.md](SCRIPTS.md) - Advanced script management patterns

## Key Differences from Other Tools

### vs pip
- **Speed:** 8-100x faster
- **Lock files:** Built-in universal lockfiles
- **Python management:** Can install Python versions
- **Unified:** Replaces pip + pip-tools + virtualenv

### vs Poetry
- **Speed:** Significantly faster resolution and installation
- **Lock files:** Universal (cross-platform in one file)
- **Simpler:** Less configuration required
- **Compatible:** Reads Poetry's pyproject.toml

### vs Conda
- **Scope:** Python-only (doesn't handle system dependencies)
- **Speed:** Much faster for Python packages
- **Compatibility:** Standard PyPI ecosystem
- **Not a replacement:** Use Conda when you need non-Python dependencies

## Support and Resources

- **Documentation:** https://docs.astral.sh/uv/
- **GitHub:** https://github.com/astral-sh/uv
- **Discord:** Join Astral's community
- **Changelog:** https://github.com/astral-sh/uv/releases

## Summary

UV standardizes Python development by unifying package management, environment management, Python version management, and script execution into a single fast tool. The key workflow is:

1. `uv init` to create projects
2. `uv add` to manage dependencies
3. `uv run` to execute code
4. `uv sync --frozen` in CI/CD
5. Commit `uv.lock` and `.python-version`

This provides consistent, fast, reproducible Python workflows across all platforms.