Python

Python requirements.txt Version Conflicts, How to Resolve

A version conflict in requirements.txt means two or more packages you depend on require incompatible versions of the same underlying dependency — pip can only install one version of a given package at a time, so it has to fail rather than silently pick one and risk breaking something.

The Problem

Running pip install -r requirements.txt fails with a message identifying conflicting requirements:

ERROR: Cannot install package-a==2.1.0 and package-b==1.5.0 because these
package versions have conflicting dependencies.

The conflict is caused by:
    package-a 2.1.0 depends on requests>=2.28.0
    package-b 1.5.0 depends on requests<2.26.0

Two packages you both genuinely need each require a different, incompatible version of a shared dependency (requests, in this example).

Why It Happens

This isn't really a bug in pip — it's pip correctly refusing to create an environment that can't actually satisfy every package's stated requirements simultaneously. Common underlying causes:

  • One of the conflicting packages is significantly outdated in your requirements file, pinned to an old version that hasn't been updated to work with newer versions of a shared dependency
  • A package you depend on directly conflicts with a dependency required by a different package you also depend on directly, with no version of either that satisfies both simultaneously
  • Overly strict version pins (using == for every package) leave pip no flexibility to find a compatible combination, even when one technically exists within a slightly wider version range
  • Two packages serve genuinely overlapping purposes and were never designed to coexist in the same environment with compatible dependency requirements

The Fix

First, identify exactly which packages and versions are in conflict from the error message — modern pip is generally good about naming the specific conflicting requirements directly, as shown above, rather than leaving you to guess.

Check whether either conflicting package has a newer version available that relaxes its dependency requirement. Often, simply updating the older, more restrictive package resolves the conflict without needing to change anything else:

pip index versions package-b

If a newer version of package-b supports the newer requests version package-a needs, updating the pin in requirements.txt resolves the conflict directly.

Relax overly strict version pins where reasonable, using range specifiers instead of exact pins, giving pip room to find a version that satisfies every package's constraints simultaneously:

# Too strict - leaves no room for pip to find a compatible version
requests==2.25.0

# More flexible - lets pip pick a version compatible with everything else
requests>=2.25.0,<3.0.0

For a more systematic approach on larger projects, use a dependency resolver tool like pip-tools, which compiles a fully resolved, compatible set of pinned versions from a higher-level list of direct dependencies, handling the resolution complexity for you rather than requiring manual trial and error:

pip install pip-tools
pip-compile requirements.in

This generates a fully pinned requirements.txt with versions confirmed compatible across your entire dependency tree, based on the looser constraints you specify in requirements.in.

If two packages genuinely cannot coexist due to a fundamental incompatibility (rather than just an outdated pin), consider whether one can be replaced with an alternative library that serves the same purpose without the conflicting dependency, or whether isolating them into separate virtual environments for separate parts of your workflow is more practical than forcing them into the same environment.

Still Not Working?

If the conflict involves a deeply nested transitive dependency (not something you directly listed, but something several layers down the dependency tree), use pip install --dry-run (available in recent pip versions) to see what pip would attempt without actually installing anything, which can help clarify exactly where in the chain the conflict originates before committing to any change:

pip install --dry-run -r requirements.txt

For particularly stubborn conflicts, creating a fresh virtual environment and installing packages one at a time, in order of importance, often surfaces the specific conflict more clearly than trying to resolve everything from a single large requirements file at once.

You might also like