This glossary defines codebase-specific terms, jargon, and domain concepts used throughout the uv project. It provides technical context and pointers to the relevant implementations for onboarding engineers.
Unlike standard pip which resolves dependencies for a single specific environment (the current one), uv performs "universal resolution". This means it finds a set of dependencies that satisfy all possible target environments allowed by the project's requires-python and supported markers.
UniversalMarker and ConflictMarker to track which dependencies apply to which environments within a single lockfile.Resolver uses PubGrub to solve for a Manifest that covers the cross-section of supported platforms.UniversalMarker: crates/uv-resolver/src/lib.rs33ConflictMarker: crates/uv-resolver/src/lib.rs32VERSION / REVISION of lockfile: crates/uv-resolver/src/lock/mod.rs82-86Inspired by Cargo, a workspace is a collection of one or more packages (members) that share a single lockfile and a common root. This allows for efficient management of monorepos.
uv searches for a pyproject.toml containing workspace definitions.list, metadata, and dir. The metadata command exports structured JSON including module owners and dependency graphs.0.10.0, workspace-dir and workspace-list are stable.WorkspaceMember: crates/uv-resolver/src/lock/mod.rs58TreeJsonTarget (for uv tree JSON): crates/uv-resolver/src/lock/mod.rs68uv can download and manage Python interpreters automatically, reducing reliance on system-installed Python. These are typically fetched from python-build-standalone.
uv performs sysconfig patching during installation to ensure managed Pythons behave correctly.uv python upgrade is stable as of 0.10.0, supporting minor version directories for transparent patch upgrades.pypy3.10 instead of python3.10).PythonRequirement: crates/uv-resolver/src/lib.rs22Managed Python Documentation: docs/concepts/python-versions.md6-12python-upgrade (stable): docs/concepts/python-versions.md157-171Dependency groups (PEP 735) allow users to categorize dependencies within their pyproject.toml (e.g., dev, test, docs).
[dependency-groups] in pyproject.toml.toolchain.rs LockedTool mechanism allows running tools directly from dependency groups.DependencyGroupsWithDefaults: crates/uv-resolver/src/lock/mod.rs21Experimental features that are not yet stable. They are typically opt-in via CLI flags, environment variables, or configuration files (uv.toml / pyproject.toml).
uv-preview crate and the PreviewFeature enum.uv audit, uv format, uv check (powered by ty), native-auth, pylock.toml, malware-check, s3-endpoint, gcs-endpoint, centralized-project-envs, tool-install-locks.python-upgrade, add-bounds, extra-build-dependencies, workspace-dir, and workspace-list became stable in 0.10.0.index-specific hash-algorithm, workspace cross-references.PreviewFeature enum: crates/uv-resolver/src/lock/mod.rs49PreviewState management: crates/uv-preview/src/lib.rs15-18uv can automatically select the appropriate PyTorch index (e.g., CPU vs CUDA) based on detected hardware.
torch_backend and hardware detection logic.torch_backend setting: crates/uv/tests/sync/show_settings.rs146| Term | Definition | Code Pointer |
|---|---|---|
| Sdist | Source Distribution. A distribution format that must be built into a wheel before installation. | crates/uv-resolver/src/lock/mod.rs26 |
| Wheel | A built distribution format (PEP 427) that can be installed directly. | crates/uv-resolver/src/lock/mod.rs26 |
| PubGrub | The version solving algorithm used by uv to resolve dependencies. | crates/uv-resolver/src/lib.rs66 |
| PEP 508 | The standard for dependency specification markers. | crates/uv-resolver/src/lock/mod.rs43-45 |
| PEP 517 | The standard for build backends and isolation. | crates/uv-resolver/src/lock/mod.rs24 |
| PEP 440 | The standard for version specifiers and ranges. | crates/uv-resolver/src/lock/mod.rs42 |
| PEP 723 | Inline script metadata for single-file Python scripts. | docs/guides/scripts.md139-141 |
| PEP 735 | Dependency groups specification. | crates/uv-resolver/src/lock/mod.rs21 |
| Fork Markers | Markers that cause the resolver to "fork" its state to handle environment-specific requirements. | crates/uv-resolver/src/lock/mod.rs88-152 |
| Ephemeral Env | Temporary virtual environments created for uv run or script execution. | docs/concepts/tools.md33-36 |
| Link Modes | File installation strategies: hardlink, reflink, or copy. Reflinks are default on Linux as of 0.10.5. | crates/uv/tests/sync/show_settings.rs198 |
| CycloneDX | Software Bill of Materials (SBOM) export format supported via uv workspace metadata. | crates/uv-resolver/src/lock/mod.rs64-65 |
| uv-bin-install | Internal mechanism used to download and run binaries like Ruff (for format) and ty (for check). | crates/uv/tests/sync/show_settings.rs150-155 |
| venv-safe-clear | Behavior where uv venv requires --clear to remove existing environments (default in 0.10.0). | crates/uv/tests/sync/show_settings.rs208 |
This diagram bridges the user's intent (CLI) to the internal resolver state and the PubGrub algorithm.
Sources: crates/uv-resolver/src/lib.rs17-31 crates/uv-resolver/src/lib.rs50 crates/uv-resolver/src/lib.rs66
This diagram tracks how uv finds or installs a Python interpreter based on user requests.
Sources: docs/concepts/python-versions.md8-18 docs/concepts/python-versions.md74-80 docs/guides/install-python.md23-25
PubGrubuv uses a modified version of the PubGrub algorithm. It operates on version ranges and incompatibilities to solve the dependency graph, supporting forking for universal resolution.
Resolver manages the state across forks.LockThe internal structure representing the resolved dependency graph, serialized as uv.lock (or pylock.toml in preview).
toml_writer for accelerated serialization.PythonPreferenceDefines the priority between managed Python installations and system Python installations during discovery.
Managed, System, etc.uv formatDownloads and runs Ruff (specifically version 0.15.0 / 2026 style guide as of 0.10.0). It supports version constraints and exclude-newer in preview.
uv auditA tool for scanning dependencies for security vulnerabilities.
uv checkDownloads and runs ty for type checking. It supports a --script flag and workspace-aware discovery.
native-authA preview feature that enables the use of system-native credential storage for package index authentication.
Sources:
Lock versioning: crates/uv-resolver/src/lock/mod.rs82-86PubGrub usage: crates/uv-resolver/src/lib.rs66Python discovery concepts: docs/concepts/python-versions.md8-18Preview mechanism: crates/uv-preview/src/lib.rs15-18Settings structure: crates/uv/tests/sync/show_settings.rs43-210Refresh this wiki