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

Safety and Best Practices

Version control: Always commit uv.lock and .python-version; never commit .venv.

CI/CD: Use --frozen to prevent unexpected updates; pin uv version; cache uv's global cache directory.

Security: Use uv export --require-hashes for supply chain security; review dependency updates; use uv tree to audit the dependency graph.

Development: Use uv run instead of activating venvs; create separate optional dependency groups; test with minimal dependencies before adding extras.

Where to Find What

• 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

• Workflows & examples: See reference files above for concrete examples

• Tool integration: See ci-cd-docker.md for GitHub Actions, Docker, and pre-commit hooks

• Troubleshooting: See command-reference.md for common issues and solutions

Resources

• Official documentation: https://docs.astral.sh/uv/

• GitHub repository: https://github.com/astral-sh/uv

• Migration guides: https://docs.astral.sh/uv/guides/