Python — pip dependency conflict (ResolutionImpossible)

Diagnose pip resolver failures by tracing direct and transitive constraints, relaxing incompatible pins, and using constraints files instead of disabling dependencies.

intermediatedebuggingpythonpackaging

Symptoms

ERROR: Cannot install X because these package versions have conflicting dependencies
ResolutionImpossible: resolution too deep or no matching distribution
The package installs alone but fails with the application's requirements
CI fails while a developer machine with an older environment succeeds

Possible causes

Two requirements pin incompatible versions of a shared dependency
A package requires a Python version or platform wheel that is unavailable
An extra pulls in a conflicting dependency
A transitive dependency changed its constraint in a new release
The resolver is using a different index or cached metadata

Diagnosis steps

Ask pip for a verbose, dry-run resolution

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

Interpretation

The resolver prints the candidates and the conflicting requirement chain. The first conflict is more useful than the final error.

Inspect the installed dependency tree

pipdeptree --warn silence

Interpretation

The tree shows which package requires the conflicting version and whether the conflict exists in the current environment.

Check available versions and Python compatibility

pip index versions PACKAGE

Interpretation

A version may exist but not for the current Python version or platform. The error text often includes the supported range.

Root cause

The set of version constraints has no solution for the current Python version and platform. The conflict is usually a direct pin, a transitive requirement, or an extra that pulls a different version.

Fix

Relax exact pins to compatible ranges, move shared constraints into a constraints file, choose versions that satisfy both packages, and isolate unrelated tools in separate environments. Do not use --no-deps or --force-reinstall to bypass the resolver.

Risk note

Ignoring dependencies can produce runtime ImportError or ABI mismatches. Pinning an old package to silence the resolver can leave known vulnerabilities unpatched.

Verify the fix

Recreate a clean virtual environment, install from the revised requirements, run pip check, and execute the application tests. Verify the lock or constraints file is committed and CI uses the same Python version.

The resolver is doing its job

A dependency conflict means the requested constraints have no common solution. The final error lists the packages, but the useful information is the chain of requirements that forced the incompatible versions. Run a verbose dry run and read the first conflict, not only the last line.

pip install --dry-run -v -r requirements.txt
pipdeptree --warn silence

Separate direct pins from shared constraints

If the application pins libfoo==1.2.0 and another package requires libfoo>=1.3, no resolver can satisfy both. Relax the direct pin to a range, or choose a version of the other package that supports 1.2. Put shared version bounds in a constraints file so every requirements file applies the same rule.

# constraints.txt
libfoo>=1.3,<2

Check Python and platform wheels

A package may have a version that supports your Python version but no wheel for your platform, forcing a source build that fails. Check pip index versions and the error’s supported tags. Use a supported Python version or a platform with a wheel rather than forcing an unsupported combination.

Verify in a clean environment

A developer environment may already have a compatible package installed, masking the conflict. Recreate a virtual environment, install from the revised requirements, run pip check, and run the tests. Commit the lock or constraints file and make CI use the same Python version. Never use --no-deps as the fix; it defers the failure to runtime.