uv-package-manager

• 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)

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

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

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

Starting a New Project

```bash

# 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 ruff mypy

# Run application

uv run python -m my_project

# Run tests

uv run pytest

```

Working with Existing Project

```bash

# 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

```bash

# 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

```bash

# 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

```

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

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

Pre-commit hooks:

```yaml

# .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:

```json

// .vscode/settings.json

{

"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",

"python.terminal.activateEnvironment": true

}

```

GitHub Actions:

```yaml

• uses: astral-sh/setup-uv@v2

with:

enable-cache: true

• run: uv sync --frozen
• run: uv run pytest

```

Common issues and solutions:

```bash

# 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

```

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

• Official documentation:
• GitHub repository:
• Migration guides:
• Comparison with other tools: