astral-sh/uv

Glossary

Project-specific vocabulary used in the uv codebase. Many terms come from PEP standards and the broader Python packaging world; the entries below explain them in the context of this repo.

Distribution terms

Distribution — a packaged build of a Python project. uv uses two flavors:

Wheel (built distribution, .whl) — a zip with a fixed layout, installable by copying files. Filename parsing lives in crates/uv-distribution-filename/.
Source distribution / sdist (.tar.gz, .zip) — a tarball that needs a PEP 517 build to produce a wheel. Built by uv via uv-build-frontend.

Index — a PyPI-compatible package index. Configured via index-url, extra-index-url, or the multi-index [[tool.uv.index]] table. See crates/uv-distribution-types/src/index.rs and index_url.rs.

Flat index — a directory or URL serving wheels and sdists without the Simple API.

Resolution terms

Resolver — uv's dependency solver. Implemented in uv-resolver, built on the PubGrub algorithm.

Universal resolution — uv's default mode. Solves for all supported Python versions and platforms simultaneously and produces a single lockfile that works everywhere. Contrasts with pip's per-environment resolution.

Fork — a marker-disjoint subspace of the resolution. When a package's dependencies vary across platforms or Python versions, the resolver "forks" to explore each branch and combines the result with marker expressions. Implemented in crates/uv-resolver/src/resolver/environment.rs.

Universal marker — a logical conjunction of a PEP 508 marker tree and a "conflict marker" that disambiguates extras / dependency-group selections. See crates/uv-resolver/src/universal_marker.rs.

Conflict marker — markers that distinguish lock entries enabled by different extras or dependency groups, so a single lockfile can describe mutually-incompatible installs.

Resolution mode — highest (default), lowest, or lowest-direct. See crates/uv-resolver/src/resolution_mode.rs.

Pre-release mode — disallow, allow, if-necessary, explicit, if-necessary-or-explicit. See crates/uv-resolver/src/prerelease.rs.

Exclude-newer / exclude-newer-package — drop candidates uploaded after a cutoff date, optionally per-package. See crates/uv-resolver/src/exclude_newer.rs.

Lockfile terms

Lockfile — the resolver's output written to uv.lock (TOML). Versioned (LockVersion) and explicitly designed for stability. Read/written in crates/uv-resolver/src/lock/mod.rs.

Pylock — a draft TOML format (PEP 751) that uv can also export via uv export --format pylock.toml. See crates/uv-resolver/src/lock/mod.rs::PylockToml.

Resolution graph — the in-memory graph of resolved nodes annotated with markers and extras. See crates/uv-resolver/src/resolution/.

Project terms

Workspace — a Cargo-style multi-package layout. A root pyproject.toml declares [tool.uv.workspace] members; uv resolves them together. See crates/uv-workspace/src/workspace.rs.

Project — a single pyproject.toml-described Python package. Workspace members are also projects.

Project environment — .venv in the project root, populated from uv.lock by uv sync.

Group — PEP 735 dependency group. uv supports [dependency-groups], with dev as a default group enabled by uv sync.

PEP 723 script — a single-file Python script with inline metadata (# /// script block) declaring dependencies and a requires-python. Parsed by uv-scripts.

Python management

Managed Python — a CPython or PyPy build downloaded by uv from python-build-standalone (CPython) or the upstream PyPy releases. Installed under python-dir (uv python dir).

Python preference — controls whether uv prefers managed or system interpreters during discovery. Values: only-managed, managed, system, only-system (see crates/uv-python/src/discovery.rs::PythonPreference).

Python downloads — controls auto-download of managed Python: automatic, manual, never.

Variant — a Python build flavor like freethreaded, debug, or t (the suffix used for free-threaded CPython). See crates/uv-python/src/discovery.rs::PythonVariant.

Marker environment — the set of PEP 508 marker values for a specific interpreter, derived from a small Python introspection script. See crates/uv-python/src/interpreter.rs.

Caching and HTTP

Cache bucket — a versioned subdirectory of ~/.cache/uv (simple-v18, wheels-v6, …) used to invalidate caches across breaking changes. See crates/uv-cache/src/lib.rs::CacheBucket.

Archive — uv's name for an unpacked wheel cached on disk for re-linking into venvs. Stored as a content-addressed directory; ArchiveId is the symlink target.

Cached client — an HTTP client wrapper that reads/writes zstd-compressed rkyv archives of registry responses, keyed by URL. See crates/uv-client/src/cached_client.rs.

rkyv — the zero-copy serialization format used for cache files and for some on-disk versions/specifiers, enabling fast metadata loads.

Builds

PEP 517 — Python's standard build interface. uv ships both a frontend (uv-build-frontend) that calls into other backends and a backend (uv-build-backend) that produces wheels and sdists for pure-Python projects.

Build isolation — building each sdist in a fresh environment with only the build-system requirements installed. Disabled per-package via --no-build-isolation or tool.uv.no-build-isolation-package.

Build context — the trait abstraction in crates/uv-types that lets resolution call back into install/build logic without circular crate dependencies.

Tools

Tool — a Python CLI installed in its own environment, like ruff or pytest installed via uv tool install. Managed by uv-tool.

uvx — the alias for uv tool run. Spawns an ephemeral environment for a single tool invocation.

Tool receipt — a uv-receipt.toml file inside each tool environment that records the install command, requested versions, and entry points so they can be re-linked or upgraded later.

Trampolines

Trampoline — a small Windows executable copied into a venv's Scripts/ directory that launches the venv's Python with a specific entry point. Built ahead of time from the nightly-only crates/uv-trampoline/ crate and embedded into uv via uv-trampoline-builder.

Authentication

Realm — host + scheme + port triple used to scope cached credentials. See crates/uv-auth/src/realm.rs.

Trusted publishing — OIDC-based publishing to PyPI without long-lived API tokens. uv supports GitHub Actions, GitLab, and pyx flavors (crates/uv-publish/src/trusted_publishing/).

Credentials cache — in-memory store of credentials parsed from URLs, keyrings, or .netrc. See crates/uv-auth/src/cache.rs.

Filesystem and platform

Simplified path — Path::user_display() from crates/uv-fs/, which renders paths relative to the user's home directory or current directory. Used in error messages.

Locked file — a cross-platform file lock primitive from crates/uv-fs/. Used to serialize cache writes and venv mutations.

Junction — a Windows directory symlink type used by uv for managed-Python links. See crates/uv-fs/ and crates/uv-python/src/macos_dylib.rs for the macOS counterpart.