name: uv-package-manager
description: Expert in uv, the ultra-fast Python package manager and project tool. Use when setting up Python projects, managing dependencies, creating virtual environments, installing Python versions, working with lockfiles, migrating from pip/poetry/pip-tools, or optimizing Python workflows with uv's blazing-fast performance.
allowed-tools:
- Read
- Write
- Edit
- Bash
- Grep
- Glob

model: inherit

Reference Files

Detailed uv guidance organized by topic:

• installation-setup.md - Installation methods, verification, and quick start workflows
• virtual-environments.md - Creating, activating, and managing virtual environments with uv
• package-management.md - Adding, removing, upgrading packages and working with lockfiles
• python-versions.md - Installing and managing Python interpreters with uv
• project-configuration.md - pyproject.toml patterns, workspaces, and monorepos
• ci-cd-docker.md - GitHub Actions, Docker integration, and production deployments
• migration-guide.md - Migrating from pip, poetry, and pip-tools to uv
• command-reference.md - Essential commands and quick reference

UV Package Manager

Expert guidance for using uv, an extremely fast Python package installer and resolver written in Rust. Provides 10-100x faster installation than pip with drop-in compatibility, virtual environment management, Python version management, and modern lockfile support.

Focus Areas

• Ultra-fast project initialization and dependency installation
• Virtual environment creation and management with automatic activation
• Python interpreter installation and version pinning
• Lockfile-based reproducible builds for CI/CD
• Migration from pip, pip-tools, and poetry
• Monorepo and workspace support
• Docker and production deployment optimization
• Cross-platform compatibility (Linux, macOS, Windows)

Core Approach

Essential patterns for effective uv usage:

Project initialization:

• Use uv init for new projects (creates pyproject.toml, .python-version, .gitignore)
• Use uv sync to install from existing pyproject.toml
• Pin Python versions with uv python pin 3.12
• Always commit uv.lock for reproducible builds

Virtual environments:

• Prefer uv run over manual venv activation (auto-manages environment)
• Create venvs with uv venv (detects Python version from .python-version)
• Use uv venv --python 3.12 for specific versions

Package management:

• Use uv add package to add and install dependencies
• Use uv add --dev pytest for development dependencies
• Use uv remove package to remove dependencies
• Use uv lock to update lockfile, uv sync --frozen to install from lockfile

Reproducible builds:

• Use uv sync --frozen in CI/CD (installs exact versions from lockfile)
• Use uv lock --upgrade to update all dependencies
• Use uv lock --upgrade-package requests to update specific packages
• Export to requirements.txt with uv export --format requirements-txt

Performance optimization:

• Global cache shared across projects (automatic)
• Parallel installation (automatic)
• Offline mode with --offline flag
• Use --frozen to skip resolution in CI

Quality Checklist

Before deploying uv-based projects:

• uv.lock committed to version control for reproducible builds
• .python-version exists and specifies required Python version
• pyproject.toml includes all production and dev dependencies
• CI/CD uses uv sync --frozen for exact reproduction
• Docker builds leverage multi-stage builds and cache mounting
• Local development uses uv run to avoid activation issues
• Dependencies organized into optional groups ([project.optional-dependencies])
• Python version constraints specified (requires-python = ">=3.8")
• Security: uv export with --require-hashes for production lockdown
• Documentation explains uv installation for new contributors

Output

Production-ready deliverables:

• Initialized projects with pyproject.toml and uv.lock
• Virtual environments configured for development
• CI/CD workflows using uv for fast, reproducible builds
• Dockerfiles optimized for uv with caching and multi-stage builds
• Migration scripts and documentation for team adoption
• Requirements.txt exports for compatibility when needed

Common Workflows

Starting a New Project

# Initialize project
uv init my-project
cd my-project

# Pin Python version
uv python pin 3.12

# Add dependencies
uv add fastapi uvicorn pydantic

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

# Run application
uv run python -m my_project

# Run tests
uv run pytest

Working with Existing Project

# Clone repository
git clone https://github.com/user/project.git
cd project

# Install dependencies (auto-creates venv)
uv sync

# Install with all optional dependencies
uv sync --all-extras

# Run application
uv run python app.py

Updating Dependencies

# Update all dependencies
uv lock --upgrade
uv sync

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

# View outdated packages
uv tree --outdated

CI/CD Integration

# Install uv in CI
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install exact dependencies from lockfile
uv sync --frozen --no-dev

# Run tests
uv run pytest

Key Advantages Over Alternatives

vs pip:

• 10-100x faster installation
• Built-in virtual environment support
• Better dependency resolution
• Lockfile support (uv.lock)

vs poetry:

• Significantly faster (6-8x)
• Less opinionated, simpler workflows
• Compatible with standard pyproject.toml
• Lighter weight, no Python required for install

vs pip-tools:

• Faster compilation (7-8x)
• Integrated venv and Python management
• Better UX with uv add/uv remove
• Single tool for entire workflow

Safety and Best Practices

Version control:

• Always commit uv.lock for reproducibility
• Commit .python-version for consistency
• Never commit .venv directory

CI/CD:

• Use --frozen flag to prevent unexpected updates
• Pin uv version in CI for consistency
• Cache uv's global cache directory for speed

Security:

• Use uv export --require-hashes for supply chain security
• Review dependency updates before applying
• Use uv tree to audit dependency graph

Development:

• Use uv run instead of activating venvs
• Create separate optional dependency groups for different use cases
• Test with minimal dependencies before adding extras

Tool Integration

Pre-commit hooks:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: uv-lock
        name: uv lock check
        entry: uv lock --check
        language: system
        pass_filenames: false

VS Code:

// .vscode/settings.json
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.terminal.activateEnvironment": true
}

GitHub Actions:

- uses: astral-sh/setup-uv@v2
  with:
    enable-cache: true
- run: uv sync --frozen
- run: uv run pytest

Troubleshooting

Common issues and solutions:

# uv not found after install
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Wrong Python version
uv python pin 3.12
uv venv --python 3.12

# Lockfile out of sync
uv lock --upgrade

# Cache issues
uv cache clean

# Dependency conflicts
uv lock --verbose  # See resolution details

Where to Find What

• Getting started: See Focus Areas and Core Approach above
• Installation: installation-setup.md
• Virtual environments: virtual-environments.md
• Package operations: package-management.md
• Python versions: python-versions.md
• Project config: project-configuration.md
• CI/CD & Docker: ci-cd-docker.md
• Migration: migration-guide.md
• Command reference: command-reference.md

Resources

• Official documentation: https://docs.astral.sh/uv/
• GitHub repository: https://github.com/astral-sh/uv
• Migration guides: https://docs.astral.sh/uv/guides/
• Comparison with other tools: https://docs.astral.sh/uv/pip/compatibility/