acaprino/uv-package-manager

UV Package Manager

Use uv - an extremely fast Python package installer and resolver written in Rust - for modern Python project management and dependency workflows.

When to Invoke

• Setting up new Python projects or managing dependencies
• Creating and managing virtual environments
• Installing or switching Python interpreter versions
• Resolving dependency conflicts efficiently
• Migrating from pip, pip-tools, or poetry to uv
• Speeding up CI/CD pipelines with faster installs
• Working with lockfiles for reproducible builds
• Managing monorepo Python projects with workspaces

Core Concepts

What is uv?

• Ultra-fast package installer: 10-100x faster than pip
• Written in Rust: Leverages Rust's performance
• Drop-in pip replacement: Compatible with pip workflows
• Virtual environment manager: Create and manage venvs
• Python installer: Download and manage Python versions
• Lockfile support: Reproducible installations

UV vs Traditional Tools

• vs pip: 10-100x faster, better resolver
• vs pip-tools: Faster, simpler, better UX
• vs poetry: Faster, less opinionated, lighter
• vs conda: Faster, Python-focused

Installation

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

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

# Using pip
pip install uv

# Using Homebrew (macOS)
brew install uv

# Verify
uv --version

Quick Start

# Create new project
uv init my-project
cd my-project

# Install packages (creates venv if needed)
uv add requests pandas

# Install dev dependencies
uv add --dev pytest black ruff

# Install from requirements.txt
uv pip install -r requirements.txt

# Sync from pyproject.toml
uv sync

Virtual Environment Management

# Create virtual environment
uv venv
uv venv --python 3.12
uv venv my-env

# Activate
source .venv/bin/activate          # Linux/macOS
.venv\Scripts\activate.bat         # Windows CMD
.venv\Scripts\Activate.ps1         # Windows PowerShell

# Or skip activation with uv run
uv run python script.py
uv run pytest
uv run --python 3.11 python script.py

Package Management

Adding Dependencies

uv add requests
uv add "django>=4.0,<5.0"
uv add numpy pandas matplotlib
uv add --dev pytest pytest-cov
uv add --optional docs sphinx
uv add git+https://github.com/user/repo.git
uv add git+https://github.com/user/[email protected]
uv add ./local-package
uv add -e ./local-package

Removing and Upgrading

uv remove requests
uv remove --dev pytest
uv add --upgrade requests
uv sync --upgrade
uv tree --outdated

Locking Dependencies

uv lock
uv lock --upgrade
uv lock --upgrade-package requests
uv lock --check

Python Version Management

uv python install 3.12
uv python install 3.11 3.12 3.13
uv python list
uv python list --all-versions
uv python pin 3.12

Project Configuration

pyproject.toml with uv

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0.0",
    "click>=8.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = []

[tool.uv.sources]
my-package = { git = "https://github.com/user/repo.git" }

Using uv with Existing Projects

# Migrate from requirements.txt
uv add -r requirements.txt

# Migrate from poetry (already have pyproject.toml)
uv sync

# Export to requirements.txt
uv pip freeze > requirements.txt

# Export with hashes
uv pip freeze --require-hashes > requirements.txt

Best Practices

Project Setup

1. Always use lockfiles for reproducibility
2. Pin Python version with .python-version
3. Separate dev dependencies from production
4. Use uv run instead of activating venv
5. Commit uv.lock to version control
6. Use --frozen in CI for consistent builds
7. Leverage global cache for speed
8. Use workspace for monorepos
9. Export requirements.txt for compatibility
10. Keep uv updated for latest features

Essential Commands

# Project management
uv init [PATH]              # Initialize project
uv add PACKAGE              # Add dependency
uv remove PACKAGE           # Remove dependency
uv sync                     # Install dependencies
uv lock                     # Create/update lockfile

# Virtual environments
uv venv [PATH]              # Create venv
uv run COMMAND              # Run in venv

# Python management
uv python install VERSION   # Install Python
uv python list              # List installed Pythons
uv python pin VERSION       # Pin Python version

# Package installation (pip-compatible)
uv pip install PACKAGE      # Install package
uv pip uninstall PACKAGE    # Uninstall package
uv pip freeze               # List installed
uv pip list                 # List packages

# Utility
uv cache clean              # Clear cache
uv cache dir                # Show cache location
uv --version                # Show version

References

• references/uv-reference.md - monorepo/workspace setup, CI/CD integration (GitHub Actions), Docker integration (single and multi-stage builds), lockfile workflows, performance optimization (cache, parallel, offline), tool comparisons with benchmarks (vs pip, poetry, pip-tools), pre-commit hooks, VS Code integration, extended workflow examples, troubleshooting, migration guides

Resources

• Official documentation: https://docs.astral.sh/uv/
• GitHub repository: https://github.com/astral-sh/uv
• Astral blog: https://astral.sh/blog
• Migration guides: https://docs.astral.sh/uv/guides/