Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 38 ยท Dependency Management

Resolving Dependencies and Conflicts

Understand how pip and uv resolve a dependency graph, why conflicts happen, how to read the error messages, and how to fix them with a tiny working resolver.

You ask for three packages. Each of them needs other packages, and those need more. Somewhere in that tree two packages ask for the same library with different version rules. Who wins? Dependency resolution is the process of choosing one version of every package so that every rule is satisfied at once. When no such choice exists, you get a conflict.

Modern installers (pip since 20.3, uv, Poetry, PDM) all use a backtracking resolver: they try the newest candidate, and if it leads to a dead end they step back and try an older one. In this lesson you will look at a real dependency tree, write a miniature resolver, and learn how to read and fix conflict errors.

The dependency graph

Your project's direct requirements are only the top layer. Installing them pulls in transitive dependencies.

flowchart TD
    app["your app"] --> web["webkit >=2"]
    app --> db["dblib >=1"]
    web --> http["httpcore >=3,<5"]
    db --> http2["httpcore >=4"]
    web --> util["utils"]
    http --- both["httpcore: one version must satisfy both rules"]
    http2 --- both

Both branches need httpcore, so only versions in the overlap of the rules (4.x) can be installed.

pip never installs two versions of the same package into one environment, because import httpcore can only mean one thing. That single-version rule is why conflicts exist at all.

Inspecting real metadata

Every installed package records its requirements in its metadata. You can read them with importlib.metadata:

Python Read the real requirements of a package

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.

Notice that some lines end with ; extra == "dev" or a marker like sys_platform == "win32". Those are conditional: a plain install only follows the ones whose marker is true for your machine and whose extra you asked for.

A miniature resolver

Here is the core idea in about forty lines. The "index" is a dictionary mapping each package to its versions and their requirements. The resolver picks the newest version of each package, records the constraints it adds, and backtracks when a choice leads nowhere.

Python A backtracking 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.

Read the output carefully. With both packages requested, the resolver first tries httpcore 5.0 (the newest), notices webkit forbids it, and settles on 4.2, the newest version inside every rule. With webkit alone it simply installs the newest allowed version. The impossible request returns None: no version of httpcore is both below 3.5 and at least 4.

Real resolvers add many refinements (parallel metadata downloads, caches, smarter ordering, wheels versus source builds), but the shape is the same: pick, check, backtrack.

Reading a conflict error

When resolution fails, pip prints something like this (shortened):

TEXT
ERROR: Cannot install app because these package versions have conflicting dependencies.
The conflict is caused by:
    webkit 2.1 depends on httpcore<4 and >=3
    dblib 1.5 depends on httpcore>=4
To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip to attempt to solve the dependency conflict

Read it from the top: which two packages disagree, and about what. Then decide which side you can move.

Ways to fix a conflict

  1. Upgrade the stricter package. A newer webkit may already allow the newer httpcore. This is the usual fix.
  2. Downgrade the other package to a release with a looser rule.
  3. Loosen your own constraint. An unnecessary httpcore<4 in your own file may be the real culprit.
  4. Ask the maintainer to widen an over-strict range, or open a pull request.
  5. Use an override (uv override-dependencies, pip constraints) only as a last resort and only if you have tested that it works. You are promising the installer that the rule is wrong.
  6. Split the environments. If two tools truly need incompatible libraries, install each in its own virtual environment or use pipx or uv tool to isolate applications.

Run pip check after installing. It scans the environment and reports any package whose requirements are not met. It is a fast sanity test in CI, and the check works because the metadata above is all it needs.

A dependency checker you can run

The same metadata lets you build a tiny pip check:

Python Check installed requirements

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.

The counts depend on what happens to be installed in your environment; the point is the technique. On your computer the real command is simply:

Terminal
pip check

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can an environment hold only one version of a package?

    import httpcore loads whichever copy is on the path first. Two versions would make behavior unpredictable, so installers require a single version that satisfies every rule.
  2. 2. What does a backtracking resolver do when its newest choice causes a dead end?

    Backtracking means stepping back to the last choice and trying another candidate until a consistent set is found or all options are exhausted.
  3. 3. A conflict says webkit 2.1 depends on httpcore<4 and dblib 1.5 depends on httpcore>=4. Which fix is usually best first?

    Moving to versions whose requirements overlap keeps the environment consistent. Forcing installs hides the problem until runtime.
  4. 4. What does pip check do?

    It reads package metadata and reports missing or incompatible requirements in the current environment.

Summary

  • Resolution picks one version per package so that all rules from all dependents hold at once.
  • Resolvers pick the newest candidate, check the rules and backtrack on dead ends.
  • Metadata (Requires-Dist) is readable with importlib.metadata; markers and extras make some requirements conditional.
  • Read conflict messages as "A needs X, B needs not-X", then upgrade, downgrade or loosen.
  • pip check verifies an installed environment.

Next: Lock Files and Reproducible Installs