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

code

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

pyproject.toml Essentials

toml

[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

bash

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

Migrate from requirements.txt

bash

uv init
uv add -r requirements.txt
uv lock

Create Reproducible Builds

bash

# 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

bash

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)