Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 38 ยท Projects and Practice

Project: Build a Mini Dependency Resolver

Build a working dependency resolver in Python with extras, markers, backtracking, clear conflict messages and a hash-pinned requirements output, using the packaging library.

Reading about dependency resolution is one thing; writing a resolver shows you why it is hard and why the error messages look the way they do. In this project you will build a small but real one. It understands everything from this chapter: version specifiers, environment markers, extras, backtracking, conflict messages and a hash-pinned lock output.

The "package index" is a Python dictionary, so everything runs in this page without network access. The logic, however, is the same shape as in pip and uv, built on the same packaging library.

The plan

flowchart TD
    R["root requirements"] --> P["parse requirements<br/>(name, extras, specifier, marker)"]
    P --> M{"marker true for<br/>this environment?"}
    M -- no --> S["skip it"]
    M -- yes --> C["add constraint to package"]
    C --> V["pick newest version<br/>allowed by all constraints"]
    V --> D["add that version's own requirements"]
    D --> P
    V -- "no version fits" --> B["backtrack: try an older choice<br/>of an earlier package"]

Pick a version, add its dependencies as new constraints, repeat. When nothing fits, undo the last choice.

Step 1: the fake index

Each package version lists its requirements as ordinary requirement strings. The string socks-lib; extra == 'socks' only applies when someone asked for the socks extra, and tomli; python_version < '3.11' only applies to older Pythons.

Step 2: the resolver

Python The resolver

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Study the four runs. In run 1 the newest httpcore (5.0) is excluded by webkit, so the resolver settles on 4.2, the newest version both branches allow. In run 2 the marker is true for Python 3.10, so tomli joins the result. In run 3 the extra switches on a conditional requirement. Run 4 ends in a message that names the packages and the rules in conflict, exactly the kind of text pip prints.

Step 3: write a lock file

A resolved set of names and versions becomes a lock file by adding hashes. The index here is fake, so the hash is computed from a placeholder file body; a real tool takes it from the index metadata.

Python Produce a hash-pinned requirements file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 4: test it like a real project

A resolver is a perfect candidate for tests: inputs and outputs are plain data. Good cases to write with pytest:

  • the newest compatible version is selected;
  • a marker that is false for the environment adds nothing;
  • an extra pulls in conditional requirements;
  • an impossible request raises with a readable message;
  • the same request always gives the same answer (determinism, which matters for lock files).

Package it with [project.scripts] mini-resolve = "miniresolve.cli:main" and publish it using the previous project's workflow if you like.

What real resolvers do that yours does not

  • Metadata from the network. They download or read wheel metadata lazily, only for versions they actually consider.
  • Smarter ordering. They choose the most constrained package first, which prunes dead ends early; uv uses the PubGrub algorithm, which learns from conflicts and produces much clearer error explanations.
  • Platform and Python awareness. They skip wheels incompatible with the target and can resolve for several platforms at once (universal locks).
  • Pre-releases, yanked files, Requires-Python, build dependencies, direct URLs, constraints and overrides.
  • Caching and parallelism.

Knowing the core loop makes all of those features easier to understand.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the resolver pass the extras requested for a package when evaluating markers?

    The special extra marker variable lets a package declare optional dependency groups that are activated by the requester.
  2. 2. What does backtracking do?

    When no version satisfies the collected constraints, the resolver returns to an earlier decision and tries a different version.
  3. 3. Which output is the most useful in an unsatisfiable request?

    Naming the conflicting rules and their sources tells the user which side to change.
  4. 4. Why does determinism matter for a resolver that writes lock files?

    A lock that changes between identical runs would hide real updates in noise and break reproducibility.

Summary

  • A resolver parses requirements, filters them by markers and extras, collects constraints per package, picks the newest version that satisfies all of them and recurses on that version's dependencies.
  • Backtracking and clear conflict messages are what make resolvers usable.
  • A lock is the resolved set plus hashes; an installer verifies each file against it.
  • Real resolvers add network metadata, smarter ordering and many edge cases on top of the same core.

Next: Project: Package Health Checker