uv Advanced Usage

uv is an extremely fast Python package and project manager written in Rust. It replaces pip, pip-tools, pipx, poetry, pyenv, virtualenv, and more with a single unified tool that's 10-100x faster.

Quick Reference

Task	Command
Create project	uv init myproject
Add dependency	uv add requests
Add dev dependency	uv add --dev pytest
Run command	uv run python main.py
Lock dependencies	uv lock
Sync environment	uv sync
Run tool	uvx ruff check .
Install Python	uv python install 3.12

Core Concepts

Project Structure

myproject/
├── pyproject.toml    # Project metadata and dependencies
├── uv.lock           # Universal lockfile (commit this)
├── .venv/            # Virtual environment (gitignore)
└── src/
    └── myproject/

pyproject.toml Essentials

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["requests>=2.28", "rich"]

[project.optional-dependencies]
dev = ["pytest", "ruff"]

[dependency-groups]
test = ["pytest>=8.0", "pytest-cov"]

[tool.uv]
dev-dependencies = ["ruff", "mypy"]

[tool.uv.sources]
# Use git dependency during development
mylib = { git = "https://github.com/org/mylib", branch = "main" }
# Use workspace member
shared = { workspace = true }
# Use local path
utils = { path = "../utils", editable = true }

Reference Documentation

For detailed guidance on specific topics:

• Projects — Project lifecycle: init, add, run, lock, sync, build, publish
• Workspaces — Monorepo management with shared lockfiles
• Resolution — Universal resolution, constraints, overrides, conflict handling
• Docker — Container images, multi-stage builds, cache optimization
• Scripts & Tools — PEP 723 inline metadata, uvx, tool management
• Python Versions — Installing and managing Python interpreters
• Configuration — pyproject.toml, uv.toml, environment variables
• pip Interface — Drop-in pip replacement with advanced features

Common Workflows

Start a New Project

uv init myproject
cd myproject
uv add fastapi uvicorn
uv run uvicorn main:app --reload

Migrate from requirements.txt

uv init
uv add -r requirements.txt
uv lock

Create Reproducible Builds

# Lock with timestamp for reproducibility
uv lock --exclude-newer "2025-01-01"

# Export for pip compatibility
uv export --frozen > requirements.txt

Test Against Lowest Bounds

uv run --resolution lowest pytest

Key Flags

Flag	Purpose
--frozen	Use exact lockfile versions, fail if outdated
--locked	Use lockfile, fail if missing or outdated
--no-dev	Exclude development dependencies
--all-extras	Include all optional dependencies
--upgrade	Allow upgrading locked dependencies
--resolution lowest	Use lowest compatible versions
--universal	Create platform-independent resolution (pip compile)