> ## Content Index
> Fetch the complete content index at: https://developer-service.blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# How uv Resolves Dependencies So Fast (and Why pip Feels Slow)
- URL: https://developer-service.blog/how-uv-resolves-dependencies-so-fast-and-why-pip-feels-slow/
- Published: 2026-11-17T08:06:42.000Z
- Updated: 2026-11-17T08:08:22.000Z
- Description: PubGrub, PEP 658 metadata, universal lockfiles, and the install cache — what actually happens during `uv lock`, and why pip still feels slow by comparison.
- Author: Nuno Bispo
- Tags: Python

If you have switched a project from pip to [uv](https://docs.astral.sh/uv/?ref=developer-service.blog), you know the feeling: you run the command, blink, and it is already done. The usual explanation is “it’s written in Rust”. That is true, but it is not the interesting part. Plenty of Rust tools are slow, and plenty of Python tools are fast enough.

This article walks through uv the way you would read an unfamiliar codebase: how the resolver chooses versions, where wall-clock time is spent, what a lockfile records, and which steps pip still performs that uv can omit. The **Watch it yourself** section reproduces that path with `uv lock -v` on your own machine.

If you have not settled on a workflow yet, [Forget pip and Poetry - uv Is the Future of Python Development](https://developer-service.blog/forget-pip-and-poetry-uv-is-the-future-of-python-development/) covers the tool in more detail, and [uv for Faster Teams, Fewer Environment Fires](https://developer-service.blog/uv-for-faster-teams-fewer-environment-fires/) covers adoption across a team.

---

## What a resolver has to solve

You list what you want in `pyproject.toml`, for example `fastapi>=0.110` and `pydantic>=2`. Every package you add brings its own dependencies, and those bring more in turn. The resolver must choose **one** version of each package so nothing conflicts.

In theory that can explode into a combinatorial search (the same class of problem people call SAT). In practice, Python dependency resolution is usually tame. [uv’s resolver docs](https://docs.astral.sh/uv/reference/internals/resolver/?ref=developer-service.blog) spell out why:

- Picking versions newest-first often works without undoing earlier choices.
- An existing `uv.lock` gives the resolver a head start: try those versions before exploring the index.
- Reading what each version *requires* (metadata) costs more than the choosing logic, cache or not.
- A failed resolve should say which packages fought each other, not just “no solution”.

That is why uv uses a purpose-built incremental solver instead of a generic SAT engine, and why a slow `uv lock` is usually waiting on metadata rather than grinding through backtracking.

---

## The solver loop: PubGrub

uv’s resolver is [PubGrub](https://github.com/pubgrub-rs/pubgrub?ref=developer-service.blog) (Rust port of the algorithm behind Dart’s package manager). The idea is simple: lock in one package version, pull in what it needs, move on. When two picks cannot live together, undo the last choice and try another branch.

Roughly, each round looks like this:

1. Track what is already pinned and what is still open.
2. Pick the next open package (by priority).
3. Choose a version: locked versions first, otherwise try newer releases before older ones.
4. Queue that version’s dependencies. uv prefetches their metadata while it continues solving.
5. No clash? Continue. Clash? Backtrack.

The payoff is smart backtracking. Say the solver picks `a 2`, then `b 2`, but `a 2` wants `c 1` while `b 2` wants `c 2`. There is no valid `c`. PubGrub blames the pair `a 2` \+ `b 2`, remembers that pair as forbidden, backs up to `a 2`, and tries a different `b` without repeating the same mistake.

If nothing works, those forbidden pairs become the error text, so you see which packages disagree. uv can also swap the order of two troublemakers so the conflict shows up earlier next time.

PubGrub is good engineering. It is still not where most seconds go; fetching metadata is.

---

## Where the time really goes: metadata

Before PubGrub can choose versions, it has to learn what each one depends on. That dependency lookup is usually slower than the choosing. uv works through a ladder, cheapest rung first:

1. **Tiny file on the index (**[**PEP 658**](https://peps.python.org/pep-0658/?ref=developer-service.blog)**).** PyPI can host a separate metadata file per wheel. uv reads that and never touches the wheel.
2. **A small slice of the wheel.** Wheels are zip files. uv can request only the end of the file, find the `METADATA` record inside, and stop.
3. **The full wheel.** More data, still no build step.
4. **Build from source.** Only when there is no usable wheel metadata: compile or run the package’s build backend to learn its dependencies.

![Diagram 1](https://developer-service.blog/content/images/2026/11/mermaid-1-3b1cc1cc67.png)

For most packages on PyPI, rungs one and two are enough. Full wheel downloads and source builds are the rare slow cases.

Your own app gets the same idea from [PEP 621](https://peps.python.org/pep-0621/?ref=developer-service.blog): list dependencies in `pyproject.toml` under `[project]`, and uv reads them as text instead of running `setup.py`.

The ecosystem only caught up recently. Years ago, [PEP 518](https://peps.python.org/pep-0518/?ref=developer-service.blog) pointed out that discovering dependencies often meant executing `setup.py`. PyPI started serving [PEP 658](https://peps.python.org/pep-0658/?ref=developer-service.blog) metadata in May 2023; uv shipped in February 2024\. Andrew Nesbitt’s [write-up](https://nesbitt.io/2025/12/26/how-uv-got-so-fast?ref=developer-service.blog) argues the same thing: the speed story is as much standards timing as it is Rust.

Inside uv, wheel metadata is parsed in the binary itself. Python subprocesses are for old packages that offer no other option. Version strings become compact integers for fast comparisons. Rust makes that cheaper; it does not remove the need for cheap metadata on the index.

---

## Forking: one lockfile for every platform

In one active environment you get one version of each package. Yet your *spec* can ask for different versions in different situations:

```text
numpy>=2,<3 ; python_version >= "3.11"
numpy>=1.16,<2 ; python_version < "3.11"

```

Those lines look contradictory until you notice the markers: on Python 3.11+ you use NumPy 2.x; below 3.11 you stay on 1.x. Only one line applies at install time.

uv’s **forking resolver** (the same idea Poetry uses) treats each marker combination as its own branch. It resolves each branch, then folds together branches that pick the same versions so `uv.lock` does not balloon. Branches can nest inside each other. The markers are [environment markers](https://packaging.python.org/en/latest/specifications/dependency-specifiers/?ref=developer-service.blog#environment-markers) in packaging terms.

One `uv.lock` can therefore cover Linux, macOS, Windows, and several Python versions. That reach applies to marker conditions, not to picking CPU-specific wheels (that is a separate wheel-tag story).

Your `requires-python` range is part of the contract too. If you declare `>=3.9`, the lock must be installable on 3.9 through whatever upper bound you imply. A dependency that demands Python 3.12 only cannot sneak in while you still advertise 3.9.

Verbose logs name the splits: `Splitting resolution on ...` and `Solving split (markers: ...)`.

---

## The lockfile: why the second run is almost free

`uv.lock` is the snapshot: exact version, hash, and download URL for every package. On the next `uv lock`, uv tries those pins first. Touch one dependency in `pyproject.toml` and it usually leaves the rest alone.

Forks need the same stability. Without saved splits, two runs could fork the graph differently just because packages were visited in another order. uv writes each branch’s `resolution-markers` into the lock so the next resolve reuses the same forks. Change requirements and you may add forks; otherwise the lock should not reshuffle.

The file sits beside `pyproject.toml`. Format is TOML: a small header, then a `[[package]]` block per dependency (versions, hashes, wheels, nested deps, and marker tables when you use forks). After `uv add fastapi`, a corner of the file looks like this:

```toml
version = 1
revision = 3
requires-python = ">=3.14"  # copied from [project]; yours matches pyproject.toml

[[package]]
name = "fastapi"
version = "0.162.5"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "starlette" },
    { name = "pydantic" },
    # ...
]
wheels = [
    { url = "https://files.pythonhosted.org/packages/.../fastapi-0.162.5-py3-none-any.whl", hash = "sha256:...", size = 12345 },
]

[[package]]
name = "starlette"
version = "1.10.0"
# ...

```

Commit the file. `uv sync --frozen` installs what it lists, nothing more.

Handy commands:

```bash
uv lock                              # resolve and write uv.lock
uv lock --upgrade-package fastapi    # bump one package, leave the rest alone
uv lock --upgrade                    # ignore locked versions and re-resolve
uv lock --check                      # CI: fail if uv.lock is out of date
uv sync --frozen                     # CI: install from the lock without re-resolving

```

---

## The install side: cache, links and parallelism

Locking picks versions. Installing still has to download wheels and put them in your venv.

pip typically copies every file into each new virtual environment. uv downloads once into a shared cache, then **links** those files into the venv (hardlinks, or copy-on-write where the filesystem allows). A second env with the same packages is mostly directory wiring, not another full copy. Find the cache with `uv cache dir`. If links misbehave on your volume, tune behavior with [\--link-mode](https://docs.astral.sh/uv/reference/settings/?ref=developer-service.blog#link-mode).

uv also downloads several packages at once, where pip often worked one-by-one. During `uv lock`, prefetching metadata overlaps network I/O with solver work so the machine is less idle.

---

## So why does pip feel slow?

pip is solid. It also has to keep behavior that made sense years ago. uv could skip a lot of that baggage.

- **Runtime.** pip is Python code on Python. uv is one binary that reads `pyproject.toml` and wheel metadata directly. Old packages still force pip to spawn build tools just to learn dependencies.
- **Legacy surface.** uv does not chase every historic format (eggs, pip’s own config files, loose metadata). pip still does.
- **Indexes.** With multiple indexes, pip may query all of them. uv stops at the first index that lists the package: fewer round trips, fewer dependency-confusion surprises.
- **Install work.** pip often downloads in a line and copies into each venv. uv caches once, links in, and fetches in parallel.

Andrew Nesbitt’s [post](https://nesbitt.io/2025/12/26/how-uv-got-so-fast?ref=developer-service.blog) makes a fair point: much of this is protocol and concurrency, not Rust. pip could adopt parts of it; breaking old workflows is the hard part.

uv’s trade-off is stricter. A borderline package may fail until the maintainer tightens metadata or you add an override.

---

## Watch it yourself

Spin up a throwaway project and resolve it with logging on:

```bash
uv init demo && cd demo
uv add fastapi httpx sqlalchemy

# Re-resolve from scratch and watch the solver work
rm uv.lock
uv lock -v 2>&1 | grep -E "Selecting|Splitting|took|Found fresh response.*metadata"

```

Verbose mode is noisy. The `grep` line keeps the interesting parts; omit it to see everything, or skip `-v` for the normal quiet run.

What to watch for:

- `Selecting ...` — uv pinned another package version.
- `Splitting resolution on ...` / `Solving split (markers: ...)` — a fork for different Python/OS markers.
- `Found fresh response for: ...metadata` — cheap metadata (index or cache), not a full wheel download.

From my machine after that demo:

![uv-lock-verbose](https://developer-service.blog/content/images/2026/11/uv-lock-verbose-1.png)

Your numbers will not match mine. Look for the rhythm: choose a version, read metadata (often from cache), repeat for each dependency.

To feel where time goes, empty the cache and time two locks back to back:

```bash
uv cache clean
rm uv.lock && time uv lock      # cold: hits the network for metadata
rm uv.lock && time uv lock      # warm: mostly reads the cache

```

The second run should be much quicker. That gap is mostly metadata, not PubGrub.

If you maintain a library and want to test whether your `>=` bounds are real, try:

```bash
uv lock --resolution lowest-direct

```

uv will lock your direct dependencies to the oldest versions your specs still allow.

---

## Practical takeaways

- Write dependencies in `pyproject.toml` so uv reads TOML instead of running build hooks.
- Commit `uv.lock` so teammates and CI get the same versions, and the next lock stays fast.
- Tighten `requires-python` to the versions you really test; broader ranges mean more fork work.
- In CI: `uv sync --frozen` to install the lock as written, `uv lock --check` to catch a stale lock before merge.
- Packages with no wheel still slow everyone down; prefer projects that publish wheels when you can.

For full pipeline recipes (GitHub Actions, GitLab CI, cache keys, Docker, and lock hygiene), see the [**uv for CI**](https://uv-for-ci.developer-service.blog/?ref=developer-service.blog) booklet.

uv got fast partly because PyPI finally exposes dependency metadata without downloading whole artifacts. pip benefits from the same PEP 658 files; uv simply started after those rules existed.

---

Follow me on Twitter: [https://twitter.com/DevAsService](https://twitter.com/DevAsService?ref=developer-service.blog)

Follow me on Instagram: [https://www.instagram.com/devasservice/](https://www.instagram.com/devasservice/?ref=developer-service.blog)

Follow me on TikTok: [https://www.tiktok.com/@devasservice](https://www.tiktok.com/@devasservice?ref=developer-service.blog)

Follow me on YouTube: [https://www.youtube.com/@DevAsService](https://www.youtube.com/@DevAsService?ref=developer-service.blog)