uv-package-manager

• Setting up new Python projects quickly
• Managing Python dependencies faster than pip
• Creating and managing virtual environments
• Installing Python interpreters
• Resolving dependency conflicts efficiently
• Migrating from pip/pip-tools/poetry
• Speeding up CI/CD pipelines
• Managing monorepo Python projects
• Working with lockfiles for reproducible builds
• Optimizing Docker builds with Python dependencies

1. 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
• Resolver: Advanced dependency resolution
• Lockfile support: Reproducible installations

2. Key Features

• Blazing fast installation speeds
• Disk space efficient with global cache
• Compatible with pip, pip-tools, poetry
• Comprehensive dependency resolution
• Cross-platform support (Linux, macOS, Windows)
• No Python required for installation
• Built-in virtual environment support

3. 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

Quick Install

```bash

# 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 (if you already have Python)

pip install uv

# Using Homebrew (macOS)

brew install uv

# Using cargo (if you have Rust)

cargo install --git https://github.com/astral-sh/uv uv

```

Verify Installation

```bash

uv --version

# uv 0.x.x

```

Create a New Project

```bash

# Create new project with virtual environment

uv init my-project

cd my-project

# Or create in current directory

uv init .

# Initialize creates:

# - .python-version (Python version)

# - pyproject.toml (project config)

# - README.md

# - .gitignore

```

Install Dependencies

```bash

# 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

# Install from pyproject.toml

uv sync

```

Pattern 1: Creating Virtual Environments

```bash

# Create virtual environment with uv

uv venv

# Create with specific Python version

uv venv --python 3.12

# Create with custom name

uv venv my-env

# Create with system site packages

uv venv --system-site-packages

# Specify location

uv venv /path/to/venv

```

Pattern 2: Activating Virtual Environments

```bash

# Linux/macOS

source .venv/bin/activate

# Windows (Command Prompt)

.venv\Scripts\activate.bat

# Windows (PowerShell)

.venv\Scripts\Activate.ps1

# Or use uv run (no activation needed)

uv run python script.py

uv run pytest

```

Pattern 3: Using uv run

```bash

# Run Python script (auto-activates venv)

uv run python app.py

# Run installed CLI tool

uv run black .

uv run pytest

# Run with specific Python version

uv run --python 3.11 python script.py

# Pass arguments

uv run python script.py --arg value

```

Pattern 4: Adding Dependencies

```bash

# Add package (adds to pyproject.toml)

uv add requests

# Add with version constraint

uv add "django>=4.0,<5.0"

# Add multiple packages

uv add numpy pandas matplotlib

# Add dev dependency

uv add --dev pytest pytest-cov

# Add optional dependency group

uv add --optional docs sphinx

# Add from git

uv add git+https://github.com/user/repo.git

# Add from git with specific ref

uv add git+https://github.com/user/repo.git@v1.0.0

# Add from local path

uv add ./local-package

# Add editable local package

uv add -e ./local-package

```

Pattern 5: Removing Dependencies

```bash

# Remove package

uv remove requests

# Remove dev dependency

uv remove --dev pytest

# Remove multiple packages

uv remove numpy pandas matplotlib

```

Pattern 6: Upgrading Dependencies

```bash

# Upgrade specific package

uv add --upgrade requests

# Upgrade all packages

uv sync --upgrade

# Upgrade package to latest

uv add --upgrade requests

# Show what would be upgraded

uv tree --outdated

```

Pattern 7: Locking Dependencies

```bash

# Generate uv.lock file

uv lock

# Update lock file

uv lock --upgrade

# Lock without installing

uv lock --no-install

# Lock specific package

uv lock --upgrade-package requests

```

Pattern 8: Installing Python Versions

```bash

# Install Python version

uv python install 3.12

# Install multiple versions

uv python install 3.11 3.12 3.13

# Install latest version

uv python install

# List installed versions

uv python list

# Find available versions

uv python list --all-versions

```

Pattern 9: Setting Python Version

```bash

# Set Python version for project

uv python pin 3.12

# This creates/updates .python-version file

# Use specific Python version for command

uv --python 3.11 run python script.py

# Create venv with specific version

uv venv --python 3.12

```

Pattern 10: pyproject.toml with uv

```toml

[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",

]

docs = [

"sphinx>=7.0.0",

"sphinx-rtd-theme>=1.3.0",

]

[build-system]

requires = ["hatchling"]

build-backend = "hatchling.build"

[tool.uv]

dev-dependencies = [

# Additional dev dependencies managed by uv

]

[tool.uv.sources]

# Custom package sources

my-package = { git = "https://github.com/user/repo.git" }

```

Pattern 11: Using uv with Existing Projects

```bash

# Migrate from requirements.txt

uv add -r requirements.txt

# Migrate from poetry

# Already have pyproject.toml, just use:

uv sync

# Export to requirements.txt

uv pip freeze > requirements.txt

# Export with hashes

uv pip freeze --require-hashes > requirements.txt

```

Pattern 12: Monorepo Support

```bash

# Project structure

# monorepo/

# packages/

# package-a/

# pyproject.toml

# package-b/

# pyproject.toml

# pyproject.toml (root)

# Root pyproject.toml

[tool.uv.workspace]

members = ["packages/*"]

# Install all workspace packages

uv sync

# Add workspace dependency

uv add --path ./packages/package-a

```

Pattern 13: CI/CD Integration

```yaml

# .github/workflows/test.yml

name: Tests

on: [push, pull_request]

jobs:

test:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- name: Install uv

uses: astral-sh/setup-uv@v2

with:

enable-cache: true

- name: Set up Python

run: uv python install 3.12

- name: Install dependencies

run: uv sync --all-extras --dev

- name: Run tests

run: uv run pytest

- name: Run linting

run: |

uv run ruff check .

uv run black --check .

```

Pattern 14: Docker Integration

```dockerfile

# 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

RUN uv sync --frozen --no-dev

# Copy application code

COPY . .

# Run application

CMD ["uv", "run", "python", "app.py"]

```

Optimized multi-stage build:

```dockerfile

# Multi-stage Dockerfile

FROM python:3.12-slim AS builder

# Install uv

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

# Install dependencies to venv

COPY pyproject.toml uv.lock ./

RUN uv sync --frozen --no-dev --no-editable

# Runtime stage

FROM python:3.12-slim

WORKDIR /app

# Copy venv from builder

COPY --from=builder /app/.venv .venv

COPY . .

# Use venv

ENV PATH="/app/.venv/bin:$PATH"

CMD ["python", "app.py"]

```

Pattern 15: Lockfile Workflows

```bash

# Create lockfile (uv.lock)

uv lock

# Install from lockfile (exact versions)

uv sync --frozen

# Update lockfile without installing

uv lock --no-install

# Upgrade specific package in lock

uv lock --upgrade-package requests

# Check if lockfile is up to date

uv lock --check

# Export lockfile to requirements.txt

uv export --format requirements-txt > requirements.txt

# Export with hashes for security

uv export --format requirements-txt --hash > requirements.txt

```

Pattern 16: Using Global Cache

```bash

# UV automatically uses global cache at:

# Linux: ~/.cache/uv

# macOS: ~/Library/Caches/uv

# Windows: %LOCALAPPDATA%\uv\cache

# Clear cache

uv cache clean

# Check cache size

uv cache dir

```

Pattern 17: Parallel Installation

```bash

# UV installs packages in parallel by default

# Control parallelism

uv pip install --jobs 4 package1 package2

# No parallel (sequential)

uv pip install --jobs 1 package

```

Pattern 18: Offline Mode

```bash

# Install from cache only (no network)

uv pip install --offline package

# Sync from lockfile offline

uv sync --frozen --offline

```

uv vs pip

```bash

# pip

python -m venv .venv

source .venv/bin/activate

pip install requests pandas numpy

# ~30 seconds

# uv

uv venv

uv add requests pandas numpy

# ~2 seconds (10-15x faster)

```

uv vs poetry

```bash

# poetry

poetry init

poetry add requests pandas

poetry install

# ~20 seconds

# uv

uv init

uv add requests pandas

uv sync

# ~3 seconds (6-7x faster)

```

uv vs pip-tools

```bash

# pip-tools

pip-compile requirements.in

pip-sync requirements.txt

# ~15 seconds

# uv

uv lock

uv sync --frozen

# ~2 seconds (7-8x faster)

```

Pattern 19: Starting a New Project

```bash

# Complete workflow

uv init my-project

cd my-project

# Set Python version

uv python pin 3.12

# Add dependencies

uv add fastapi uvicorn pydantic

# Add dev dependencies

uv add --dev pytest black ruff mypy

# Create structure

mkdir -p src/my_project tests

# Run tests

uv run pytest

# Format code

uv run black .

uv run ruff check .

```

Pattern 20: Maintaining Existing Project

```bash

# Clone repository

git clone https://github.com/user/project.git

cd project

# Install dependencies (creates venv automatically)

uv sync

# Install with dev dependencies

uv sync --all-extras

# Update dependencies

uv lock --upgrade

# Run application

uv run python app.py

# Run tests

uv run pytest

# Add new dependency

uv add new-package

# Commit updated files

git add pyproject.toml uv.lock

git commit -m "Add new-package dependency"

```

Pattern 21: Pre-commit Hooks

```yaml

# .pre-commit-config.yaml

repos:

- repo: local

hooks:

- id: uv-lock

name: uv lock

entry: uv lock

language: system

pass_filenames: false

- id: ruff

name: ruff

entry: uv run ruff check --fix

language: system

types: [python]

- id: black

name: black

entry: uv run black

language: system

types: [python]

```

Pattern 22: VS Code Integration

```json

// .vscode/settings.json

{

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

"python.terminal.activateEnvironment": true,

"python.testing.pytestEnabled": true,

"python.testing.pytestArgs": ["-v"],

"python.linting.enabled": true,

"python.formatting.provider": "black",

"[python]": {

"editor.defaultFormatter": "ms-python.black-formatter",

"editor.formatOnSave": true

}

}

```

Common Issues

```bash

# Issue: uv not found

# Solution: Add to PATH or reinstall

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

# Issue: Wrong Python version

# Solution: Pin version explicitly

uv python pin 3.12

uv venv --python 3.12

# Issue: Dependency conflict

# Solution: Check resolution

uv lock --verbose

# Issue: Cache issues

# Solution: Clear cache

uv cache clean

# Issue: Lockfile out of sync

# Solution: Regenerate

uv lock --upgrade

```

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

Performance Tips

```bash

# Use frozen installs in CI

uv sync --frozen

# Use offline mode when possible

uv sync --offline

# Parallel operations (automatic)

# uv does this by default

# Reuse cache across environments

# uv shares cache globally

# Use lockfiles to skip resolution

uv sync --frozen # skips resolution

```

From pip + requirements.txt

```bash

# Before

python -m venv .venv

source .venv/bin/activate

pip install -r requirements.txt

# After

uv venv

uv pip install -r requirements.txt

# Or better:

uv init

uv add -r requirements.txt

```

From Poetry

```bash

# Before

poetry install

poetry add requests

# After

uv sync

uv add requests

# Keep existing pyproject.toml

# uv reads [project] and [tool.poetry] sections

```

From pip-tools

```bash

# Before

pip-compile requirements.in

pip-sync requirements.txt

# After

uv lock

uv sync --frozen

```

Essential Commands

```bash

# 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

```

• 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/
• Comparison with other tools: https://docs.astral.sh/uv/pip/compatibility/

1. Use uv for all new projects - Start with uv init
2. Commit lockfiles - Ensure reproducible builds
3. Pin Python versions - Use .python-version
4. Use uv run - Avoid manual venv activation
5. Leverage caching - Let uv manage global cache
6. Use --frozen in CI - Exact reproduction
7. Keep uv updated - Fast-moving project
8. Use workspaces - For monorepo projects
9. Export for compatibility - Generate requirements.txt when needed
10. Read the docs - uv is feature-rich and evolving