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

Command	Purpose
`uv init`	Create new project with `pyproject.toml`
`uv add <pkg>`	Add runtime dependency
`uv remove <pkg>`	Remove dependency
`uv sync`	Install from lockfile
`uv lock`	Regenerate lockfile
`uv run <cmd>`	Run command in project venv
`uv pip install`	pip-compatible install interface
`uv python install`	Download Python interpreters

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

Alternative	Use When	Don't Use When
pip + venv	Legacy projects, minimal tooling	You need lockfiles or speed
Poetry	Team already standardized on Poetry	Starting fresh (uv is faster)
PDM	PEP 582 `__pypackages__` workflow preferred	You want a traditional `.venv`
conda/mamba	Scientific stack with C libs	Pure PyPI web apps

FAQs

Does uv replace pip entirely?

uv provides uv pip for pip-compatible commands and uv add/uv sync for project workflows. You can migrate incrementally.

Where does uv store downloaded packages?

A global cache (typically ~/.cache/uv/). Project .venv directories hardlink from the cache, saving disk space.

Can I use uv with an existing requirements.txt?

Yes: uv pip install -r requirements.txt. For long-term maintenance, migrate to pyproject.toml with uv add.

How do I upgrade a single dependency?

uv lock --upgrade-package httpx then uv sync.

Does uv work on Windows?

Yes. Install via powershell -c "irm https://astral.sh/uv/install.ps1 | iex".

What is the difference between uv sync and uv run?

uv sync installs dependencies into .venv. uv run executes a command inside that environment.

Can uv manage dev dependencies?

Yes. Use [dependency-groups] in pyproject.toml and uv sync --group dev.

How does uv compare to Poetry for publishing?

uv focuses on install speed and lockfile management. For building and publishing wheels, pair uv with hatchling or use uv build / uv publish.

Should I activate the venv when using uv?

No. uv run handles environment activation. Manual source .venv/bin/activate still works if you prefer.

How do I set a private index with uv?

export UV_INDEX_URL=https://pypi.internal/simple/ or configure [[tool.uv.index]] in pyproject.toml.

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

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

Command	Purpose
`uv init`	Create new project with `pyproject.toml`
`uv add <pkg>`	Add runtime dependency
`uv remove <pkg>`	Remove dependency
`uv sync`	Install from lockfile
`uv lock`	Regenerate lockfile
`uv run <cmd>`	Run command in project venv
`uv pip install`	pip-compatible install interface
`uv python install`	Download Python interpreters

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

Alternative	Use When	Don't Use When
pip + venv	Legacy projects, minimal tooling	You need lockfiles or speed
Poetry	Team already standardized on Poetry	Starting fresh (uv is faster)
PDM	PEP 582 `__pypackages__` workflow preferred	You want a traditional `.venv`
conda/mamba	Scientific stack with C libs	Pure PyPI web apps

FAQs

Does uv replace pip entirely?

uv provides uv pip for pip-compatible commands and uv add/uv sync for project workflows. You can migrate incrementally.

Where does uv store downloaded packages?

A global cache (typically ~/.cache/uv/). Project .venv directories hardlink from the cache, saving disk space.

Can I use uv with an existing requirements.txt?

Yes: uv pip install -r requirements.txt. For long-term maintenance, migrate to pyproject.toml with uv add.

How do I upgrade a single dependency?

uv lock --upgrade-package httpx then uv sync.

Does uv work on Windows?

Yes. Install via powershell -c "irm https://astral.sh/uv/install.ps1 | iex".

What is the difference between uv sync and uv run?

uv sync installs dependencies into .venv. uv run executes a command inside that environment.

Can uv manage dev dependencies?

Yes. Use [dependency-groups] in pyproject.toml and uv sync --group dev.

How does uv compare to Poetry for publishing?

uv focuses on install speed and lockfile management. For building and publishing wheels, pair uv with hatchling or use uv build / uv publish.

Should I activate the venv when using uv?

No. uv run handles environment activation. Manual source .venv/bin/activate still works if you prefer.

How do I set a private index with uv?

export UV_INDEX_URL=https://pypi.internal/simple/ or configure [[tool.uv.index]] in pyproject.toml.

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

uv - The Fast Toolchain

Search Documentation

uv - The Fast Toolchain