Diagnosing and Fixing PyPI Dependency Conflicts with pip

Recognizable Condition

During a pip install you may see an error that contains ResolutionImpossible or, after installation, pip check reports broken dependencies. These are clear signs that two or more packages demand incompatible versions of a shared dependency.

Common Causes

Cause	Typical Symptom
Strict version pins (e.g., == or ===)	Resolver cannot find a compatible set.
Transitive dependencies with overlapping constraints	Multiple indirect requirements conflict.
Using an old pip (<20.3) that lacks backtracking	Resolver may choose a wrong version and break later.
Mixing system‑wide and virtual‑env installations	Duplicate packages with different versions coexist.

Diagnostic Checklist

1. Confirm pip version – pip --version should be ≥20.3. If older, upgrade: python -m pip install --upgrade pip.
2. Run a dry‑run – pip install <package> --dry-run to see proposed versions without altering the environment.
3. Check current state – pip check lists any broken imports or unmet constraints.
4. Inspect the lock – pip freeze shows installed versions; compare against the requires‑dist entries in METADATA files of affected packages.
5. Identify conflicting packages – parse the error message for the pair of packages and the dependency causing the clash.

Step‑by‑Step Fixes

• Use a virtual environment – python -m venv venv then source venv/bin/activate. This isolates the solution from system packages.
• Relax constraints where possible – Replace == pins with >= or ~=> in your requirements.txt. Example: numpy>=1.21,<1.26 instead of ==1.25.0.
• Pin only the root package – Let pip resolve transitive dependencies automatically. If a transitive dependency is too restrictive, override it with a later version using --upgrade after the root install.
• Force a specific dependency version – pip install SQLAlchemy==1.4.46 before installing the conflicting packages. This pre‑installs a compatible version.
• Use pip‑tools or Poetry – These tools generate a requirements.lock that captures a consistent dependency set. Run pip-compile or poetry lock to resolve conflicts ahead of time.
• Re‑run with --no-dependencies – Install the root package first, then manually install each dependency in order of their constraints. This is a last‑resort technique that can break when a dependency has optional extras.

Concrete Example

Suppose you want to install pandas==1.5.3 and scipy==1.10.1 in the same environment. pandas requires numpy>=1.21,<1.25, while scipy requires numpy>=1.24,<1.26. The resolver will raise ResolutionImpossible because no single numpy version satisfies both ranges.

pip install pandas==1.5.3 scipy==1.10.1
# → ResolutionImpossible: Cannot find compatible numpy version

Fix:

1. Install numpy==1.24.3 first: pip install numpy==1.24.3.
2. Then install the packages: pip install pandas==1.5.3 scipy==1.10.1. The resolver will skip re‑installing numpy because the installed version satisfies both constraints.

Verify with pip check and pip freeze to confirm that all dependencies are satisfied.

Escalation Criteria

• If pip check still reports broken imports after applying the fixes, the conflict may involve optional extras or platform‑specific wheels. Check the package documentation for known issues.
• When the conflict persists across multiple environments (e.g., local, CI, production), file an issue on the package’s GitHub repository with the full error trace and the minimal requirements.txt that reproduces the problem.
• If the root package is a critical dependency for your project, consider pinning a compatible older or newer version of the conflicting package that satisfies both constraints, or replacing it with an alternative library.

Limitations and Practical Checks

• pip’s resolver only works reliably on versions ≥20.3. On older versions, dependency conflicts may surface as runtime errors rather than install‑time failures.
• Using --force-reinstall or --ignore-installed can bypass the resolver but risks breaking the environment; always test in a fresh virtual environment first.
• After any change, run pip check to ensure no dependency graph is left broken.
• Keep a requirements.txt or pyproject.toml under version control to track the exact set of working versions.