Introduction to
uv

Foundations

• What uv is — Astral, Rust, the consolidation pitch
• Installation and the first uv pip command
• Virtual environments with uv venv
• Starting a project with uv init

Origin & status

• Built by Astral — same team as ruff
• First released February 2024; 1.0 entered the project-manager era in late 2024
• Apache 2.0 / MIT dual-licensed, fully open source
• Single static Rust binary — no Python bootstrap required
• Backed by Astral's commercial roadmap, but every feature is in the open-source core

Speed (typical, cold cache → warm)

Measured by Astral; varies by network. 10–100× over pip is the rule, not the exception.

Standalone installer

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# pin a version
curl -LsSf https://astral.sh/uv/0.5.0/install.sh | sh

First sanity check

$ uv --version
uv 0.5.4

$ uv python list
cpython-3.13.0-linux-x86_64-gnu
cpython-3.12.7-linux-x86_64-gnu
cpython-3.11.10-linux-x86_64-gnu
...

$ uv pip list
Package    Version
---------- -------
(empty system pip-compatible view)

Same commands, faster

# classic pip
pip install requests
pip install -r requirements.txt
pip freeze > requirements.txt
pip install -e .
pip uninstall flask

# uv equivalent — same flags
uv pip install requests
uv pip install -r requirements.txt
uv pip freeze > requirements.txt
uv pip install -e .
uv pip uninstall flask

Create & activate

# defaults to .venv
uv venv

# pick a version
uv venv --python 3.12
uv venv --python 3.12.4
uv venv --python pypy@3.10

# pick a path
uv venv ~/envs/scratch

# activate (still POSIX as ever)
source .venv/bin/activate
.\.venv\Scripts\activate    # Windows

Create a new project

$ uv init my-app
Initialized project `my-app` at /tmp/my-app

$ tree -a my-app
my-app/
├── .gitignore
├── .python-version       # pinned Python (e.g. 3.12)
├── README.md
├── main.py               # hello-world entry
└── pyproject.toml

# init in-place
uv init --name my-app .

# library scaffold (with src/)
uv init --lib mylib

# application scaffold (default)
uv init --app my-cli

# packaged (build-system + entry points)
uv init --package my-tool

Anatomy of a uv-managed project

[project]
name = "my-app"
version = "0.1.0"
description = "Example service"
readme = "README.md"
requires-python = ">=3.11"
authors = [
  { name = "Brendan Lynskey",
    email = "you@example.com" }
]
dependencies = [
  "fastapi>=0.115",
  "httpx>=0.27",
  "pydantic>=2.8",
]

[project.optional-dependencies]
postgres = ["asyncpg>=0.29"]

[dependency-groups]
dev = [
  "pytest>=8",
  "ruff>=0.6",
  "mypy>=1.10",
]

[tool.uv]
package = true            # install in editable mode

Adding

# runtime deps
uv add fastapi httpx

# version pin
uv add 'pydantic>=2.8,<3'

# dev-group dependency
uv add --group dev pytest ruff mypy

# extras (optional dep)
uv add --optional postgres asyncpg

# from a local path / git / URL
uv add ./libs/internal-utils
uv add 'git+https://github.com/foo/bar@main'
uv add 'https://files.pythonhosted.org/packages/.../wheel.whl'

# editable
uv add --editable ./libs/internal-utils

Excerpt

version = 1
requires-python = ">=3.11"

[[package]]
name = "fastapi"
version = "0.115.4"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "pydantic" },
    { name = "starlette" },
]
sdist = { url = "...", hash = "sha256:abc..." }
wheels = [
    { url = "...py3-none-any.whl",
      hash = "sha256:def..." },
]

[[package]]
name = "pydantic"
version = "2.9.2"
...

What sync does

1. Ensure uv.lock matches pyproject.toml (re-lock if not)
2. Ensure .venv exists with the right Python
3. Install / upgrade / remove packages so .venv matches the lock exactly
4. Remove anything in the venv that is not in the lock

It is idempotent. Running it twice is essentially free.

Everyday usage

uv run python main.py
uv run pytest -q
uv run ruff check .
uv run mypy src/
uv run ipython
uv run python -c 'import torch; print(torch.__version__)'

# with extra runtime deps not in the project
uv run --with rich --with httpx python -c \
  'from rich import print; print({"hi": 1})'

# pin a Python different from .python-version
uv run --python 3.13 pytest

Install & list

uv python list                # installed + downloadable
uv python list --only-installed
uv python install 3.12.7
uv python install 3.11 3.12 3.13
uv python install 'cpython-3.12.7-linux-x86_64-gnu'
uv python install pypy@3.10

# uninstall
uv python uninstall 3.11

# show where one lives
uv python find 3.12

A real, runnable example

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "httpx>=0.27",
#   "rich>=13",
# ]
# ///
import httpx
from rich import print

r = httpx.get("https://api.github.com/zen")
print(f"[bold green]GitHub says:[/] {r.text}")

$ chmod +x zen.py
$ ./zen.py
GitHub says: Practicality beats purity.

One-shot CLI execution

# run a CLI without installing it
uvx ruff check .
uvx black .
uvx pre-commit run --all-files
uvx httpie GET https://example.com

# specific version
uvx ruff@0.6.9 check .

# from git
uvx --from 'git+https://github.com/foo/bar' baz

# pass extras / extra deps
uvx --with pandas streamlit run app.py

Layout

repo/
├── pyproject.toml           # workspace root
├── uv.lock                  # ONE lockfile
├── apps/
│   ├── api/
│   │   └── pyproject.toml
│   └── worker/
│       └── pyproject.toml
└── libs/
    ├── core/
    │   └── pyproject.toml
    └── adapters/
        └── pyproject.toml

Dependency groups (PEP 735)

Internal-only groups for dev tooling, docs, profiling — never installed by your users.

[dependency-groups]
dev      = ["pytest>=8", "ruff>=0.6"]
docs     = ["mkdocs>=1.6", "mkdocs-material"]
profile  = ["py-spy", "memray"]
typing   = ["mypy>=1.10",
            "types-requests"]

# include another group inside one
test     = [{ include-group = "dev" },
            "pytest-asyncio"]

uv sync --group dev
uv sync --group dev --group typing
uv sync --all-groups
uv run --group test pytest

Build wheels & sdists

# build into ./dist/
uv build

# only one format
uv build --wheel
uv build --sdist

# specify a workspace member
uv build --package my-lib

# inspect
unzip -l dist/my_lib-0.1.0-py3-none-any.whl

Replaces python -m build. Reads the build-system table from pyproject.toml — Hatchling, setuptools, maturin (Rust extensions), all work.

The global cache

• One content-addressed store at ~/.cache/uv/ (Linux/macOS) or %LOCALAPPDATA%\uv\cache
• Wheels, sdists, source builds, metadata — keyed by hash, deduplicated across projects
• Building NumPy from source once means every other venv on the machine gets it for free
• Inspect: uv cache dir, uv cache prune, uv cache clean

Verdicts

• pip — still the floor, fine for one-off venvs
• Poetry — mature, opinionated, slow resolver, no Python management
• pdm — closest spiritual ancestor of uv; smaller ecosystem
• Hatch — strong on builds + matrices, weaker on locking
• uv — covers all of the above, faster, single binary

Stage 1 — drop-in (no project changes)

# nothing to change in the repo, just:
alias pip='uv pip'

uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

Useful for proving uv works in your CI before any rewrite.

What changes

[tool.uv] section

[tool.uv]
# install the project itself in editable mode
package = true

# always sync these groups by default
default-groups = ["dev"]

# constrain Python versions for the lock
python-preference = "managed"
required-version  = ">=0.5"

# index configuration
index-strategy = "unsafe-best-match"
prerelease     = "if-necessary"

# resolve only certain platforms
[tool.uv.environments]
linux-x86 = "platform_system == 'Linux' and platform_machine == 'x86_64'"

# private indexes
[[tool.uv.index]]
name     = "internal"
url      = "https://pkg.acme.com/simple"
priority = "supplemental"
explicit = true

[tool.uv.sources]
mylib = { index = "internal" }

Minimal CI workflow

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: ["3.11", "3.12", "3.13"]
    steps:
      - uses: actions/checkout@v4

      - uses: astral-sh/setup-uv@v3
        with:
          version: "0.5.4"
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - run: uv python install ${{ matrix.python }}
      - run: uv sync --frozen --all-groups
      - run: uv run ruff check .
      - run: uv run mypy src/
      - run: uv run pytest -q --cov

Hardlink errors across volumes

Docker bind mounts and NFS often refuse hardlinks: error: Failed to create hard link.

# fix
export UV_LINK_MODE=copy

Editable install of the project itself

If you want import myapp to work after uv sync, add:

[tool.uv]
package = true

What we covered

• uv as the all-in-one Python toolchain
• uv pip as the drop-in path; uv add as the project path
• Universal multi-platform uv.lock
• uv sync & uv run for everyday work
• Managing Pythons, PEP 723 scripts, and uvx tools
• Workspaces, dep groups, build & publish
• Performance internals — cache, hardlinks, PubGrub
• Migration from pip-tools and Poetry
• CI patterns & gotchas