Charlie Marsh on uv: Python Dependency Resolution and Performance

Charlie Marsh, founder of Astral, introduces the team’s Rust-based Python tools: Ruff for linting and formatting, and uv for package management. This talk focuses on why uv was built, the difficult parts of Python packaging, and techniques that make it fast.

uv aims to be a fast, unified package manager: install Python, create environments, resolve and install dependencies, and build distributable packages. Marsh compares the intended experience to Cargo, where cloning and running a Rust project is relatively predictable.

Python tooling is fragmented both because there are multiple choices for a given task and because nontrivial workflows require chaining tools. uv builds its own stack rather than layering on pip, with the goal of providing a coherent experience.

Speed can change workflows, not merely save time. Marsh says Ruff made some checks practical as local hooks instead of only in CI. With uv, virtual environments can be treated as disposable because recreating them is comparatively cheap.

Marsh reports that after its February release, uv had reached roughly 16 million downloads per month and more than 10% of requests to PyPI at the time of this 2024 talk. He uses that adoption as context for the implementation lessons.

uv exposes a pip-compatible interface such as uv pip install, as well as higher-level commands such as uv sync and uv lock. Both follow a similar lifecycle: find the Python interpreter, discover requirements, resolve dependencies, and plan changes to the environment.

Resolution turns a request such as a Pydantic dependency into compatible package versions. A lockfile also records where artifacts come from, their dependencies, hashes, and sizes. The installation plan compares that desired state with what is already installed.

One difficulty is that a Python environment generally cannot use two versions of the same package at once. If one dependency requires Pydantic 2 and another requires Pydantic 1, that graph cannot be installed as specified.

If a dependency’s version is flexible, the resolver can backtrack through alternatives to find compatible versions. A realistic graph can have many packages and constraints; selecting versions so all requirements are satisfied is a Boolean satisfiability problem and is NP-hard in general.

uv uses a conflict-driven clause-learning approach to make solving practical, though there is no general guarantee of fast resolution. Marsh contrasts this with ecosystems that can sometimes escape a conflict by allowing multiple package versions.

Python requirements can also have environment markers: a dependency might apply only on Windows or only below a particular Python version. Solving for one known machine can filter irrelevant requirements, but uv aims to produce a universal lockfile usable across machines.

A universal lock does not mean every platform installs identical packages. It means users on the same applicable platform and Python version can reproduce the corresponding selection. The resolver tries a common solution, but some requirements conflict only across different environments.

For example, one requirement may need Pydantic 2 on Windows while another needs a version below 2 elsewhere. uv can fork the solve for the disjoint cases, resolve them separately, and merge the results with markers identifying where each version applies.

Dependencies common to both branches can be merged too. A marker saying Windows or not Windows is always true and can be simplified away. This requires marker algebra: combining conditions, simplifying them, and checking whether two expressions can overlap.

Checking marker disjointness is another satisfiability problem. Real expressions can become large, especially in a test resolving all optional dependencies of Transformers. The team built a normalizer based on algebraic decision diagrams to simplify and reason about markers.

A further complication is metadata: a package registry does not always provide static dependency information. If only source is published, determining dependencies may require executing Python build code or even building the package. uv tries to avoid unnecessary work while preserving correctness.

The resulting universal resolution is a graph of package versions with marker conditions on edges. At installation time, uv traverses the graph for the current environment instead of performing a second full dependency solve.

Rust contributes to uv’s performance by providing a fast baseline and control over memory, but it is not the whole explanation. Much package-manager work is I/O, and uv has continued to improve while remaining written in Rust.

Python version syntax is richer than a simple 1.0.0: it can include pre-releases, post-releases, local identifiers, epochs, and combinations of these. Release segments can be numerous, so a general representation can require vectors and allocations.

Local version identifiers have also been used by projects such as PyTorch to distinguish accelerator-compatible builds. Marsh presents that as an adaptation to a gap in existing packaging conventions, rather than a simple numeric-version case.

A team member known as BurntSushi observed that more than 90% of versions they encountered could fit into a single u64. uv uses a compact representation for those common cases and falls back to a full representation for versions that do not fit.

The eight-byte encoding reserves two bytes for the first release segment, supporting calendar-style versions, three for later release segments, and three for one pre-release or post-release specifier. It cannot represent every valid version, including epochs or more than four release segments.

The encoding is carefully ordered so that version ordering corresponds to integer ordering. Common comparisons can therefore use a single integer comparison instead of traversing allocated structures. In a difficult fully cached resolution, Marsh reports a roughly three- to fourfold speedup.

Next, consider dependency metadata. Python wheels are ZIP archives containing metadata, but some registries do not expose that metadata separately. Downloading an entire large wheel just to discover dependencies is expensive, particularly when testing multiple versions.

The ZIP central directory indexes the entries and their positions. uv can use an HTTP range request near the end of the archive to retrieve the directory, find the metadata entry, and make a second range request for that entry rather than downloading the full wheel.

Marsh says cache design is one of the largest contributors to perceived speed. Many local installations reuse packages already present on the machine, so uv optimizes these warm operations rather than repeatedly downloading and unpacking the same artifacts.

The global cache contains unpacked archives: downloaded wheels are unzipped into it as they arrive. When possible, installing into an environment uses reflinks or hard links to cached files. That makes repeated installations fast and avoids duplicating the same contents across projects.

Package metadata is different from installed files, so uv also uses zero-copy techniques. Rather than allocating a second copy of data after reading it, a structure can refer to bytes already in memory where the representation permits it.

For cached metadata, Marsh describes storing data in a form close to its in-memory representation and using the rkyv library. Validation and safety checks matter around the unsafe operations. Reading still costs more for a larger file, but converting the already-read representation avoids work proportional to ordinary parsing and copying.