uv - The Fast Toolchain

uv is an all-in-one Python package manager written in Rust. It replaces pip, venv, pip-tools, and pyenv with a single fast CLI - the recommended default for Python 3.14 projects.

Recipe

Quick-reference recipe card - copy-paste ready.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# New project
uv init myapp && cd myapp
uv add fastapi pydantic
uv run uvicorn myapp.main:app --reload
 
# Existing project
uv sync
uv run pytest

When to reach for this:

• Starting a new Python 3.14 project
• Replacing slow pip install + manual venv workflows
• CI pipelines that need sub-second dependency installs
• Managing multiple Python versions without pyenv

Working Example

#!/usr/bin/env bash
set -euo pipefail
 
# Bootstrap a FastAPI service with uv
uv init invoice-api
cd invoice-api
 
uv add "fastapi>=0.115" "uvicorn[standard]>=0.34" "pydantic>=2"
 
cat > src/invoice_api/main.py <<'PY'
from fastapi import FastAPI
from pydantic import BaseModel
 
app = FastAPI()
 
class Invoice(BaseModel):
    id: int
    amount: float
 
@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}
 
@app.post("/invoices")
def create(invoice: Invoice) -> Invoice:
    return invoice
PY
 
uv run uvicorn invoice_api.main:app --host 0.0.0.0 --port 8000

What this demonstrates:

• uv init scaffolds pyproject.toml, src/ layout, and .venv
• uv add resolves dependencies and updates uv.lock
• uv run executes inside the project environment without manual activation
• Entry points resolve from the src/ package automatically

Deep Dive

How It Works

• uv uses a global package cache and hardlinks into per-project .venv directories
• Resolution happens in Rust - typically 10-100x faster than pip for large dependency trees
• uv.lock is a universal lockfile (PEP 751 compatible) with exact versions and hashes
• uv python manages interpreter downloads alongside package management

Core Commands

Python Notes

# Pin interpreter for the project
uv python pin 3.14
 
# Run against a specific version without changing the pin
uv run --python 3.13 pytest
 
# Upgrade all dependencies
uv lock --upgrade

Gotchas

• Forgetting uv sync after clone - imports fail with ModuleNotFoundError. Fix: run uv sync (or uv sync --frozen in CI) before any command.
• Mixing pip and uv in the same venv - metadata conflicts cause subtle version skew. Fix: pick one tool per project; use uv pip if you need pip semantics.
• Not committing uv.lock - teammates get different dependency versions. Fix: commit the lockfile; use uv sync --frozen in CI.
• Running uv add without updating lock - pyproject.toml and lockfile drift. Fix: uv add updates both; if editing pyproject.toml by hand, run uv lock after.
• Global uv pip install - pollutes the system interpreter. Fix: always work inside a project (uv init / uv sync) or pass --python explicitly.

Alternatives

FAQs

Related

• Environments & Packaging Basics - venv and isolation fundamentals
• pyproject.toml Explained - project metadata structure
• Dependency Resolution & Lockfiles - pinning strategies
• Managing Python Versions - multi-version testing

Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.