pip Dependency Conflicts: Resolve Incompatible Packages (2026)

You’re trying to install a Python package, and pip throws a fit about incompatible requirements. This happens because pip installs packages in isolation, and when you try to install a new package, it checks if its dependencies conflict with what’s already installed in your environment.

Let’s say you’re trying to install requests version 2.28.0, but your environment already has urllib3 version 1.25.0 installed. requests 2.28.0 might require urllib3 version 1.26.0 or higher. pip sees this mismatch and halts the installation, telling you:

ERROR: Cannot install requests 2.28.0 because these package versions have conflicting dependencies.
The conflict is caused by:
    requests 2.28.0 depends on urllib3!=1.25.0,!=1.25.1,<1.27
    installed urllib3 1.25.0

Here’s how to break down and resolve these conflicts:

1. Understand the Conflict

The error message is your best friend. It explicitly tells you:

• Which package (requests 2.28.0) is causing the problem.
• Which of its dependencies is problematic (urllib3).
• What version of the problematic dependency is already installed (urllib3 1.25.0).
• What version of the problematic dependency is required by the new package (urllib3!=1.25.0,!=1.25.1,<1.27).

In this case, requests 2.28.0 cannot work with urllib3 1.25.0.

2. Check Your Current Environment

Before you change anything, see what’s actually installed. Command:

pip freeze

This will list all installed packages and their exact versions. Look for the packages mentioned in the error message.

3. Common Causes and Solutions

There are a few recurring reasons for these conflicts:

Cause A: Direct Dependency Conflict

This is the most straightforward. Package A needs Package C v1.x, but Package B (already installed) needs Package C v2.x.

Diagnosis: The error message will clearly state the conflicting dependency, like in our requests/urllib3 example.

Solution 1: Upgrade the Conflicting Dependency If the new package’s required version of the dependency is newer than what’s installed, and the older version isn’t strictly required by other critical packages in your environment, try upgrading.

Command:

pip install --upgrade urllib3==1.26.0

Why it works: You’re manually installing a version of urllib3 that satisfies requests 2.28.0’s requirement (<1.27 and !=1.25.0,!=1.25.1).

Solution 2: Downgrade the New Package If the new package you’re trying to install has an older version available that is compatible with your existing dependencies, try installing that.

Command:

pip install requests==2.27.0

Why it works: Let’s assume requests 2.27.0 might be compatible with urllib3 1.25.0. You’d check its requirements first (e.g., by looking at its PyPI page or running pip install requests==2.27.0 --dry-run).

Cause B: Indirect Dependency Conflict (Transitive Dependencies)

Package A needs Package B v1.0. Package B v1.0 needs Package C v1.0. But you already have Package D installed, and Package D needs Package C v2.0. pip sees that A and D can’t coexist because they require different versions of C.

Diagnosis: The error message might be less direct. It could point to Package C as the conflict, and you’ll have to trace back which installed packages require conflicting versions. pipdeptree is invaluable here.

Command:

pip install pipdeptree
pipdeptree

This command visualizes your dependency tree. You’ll see which top-level packages depend on which versions of other packages. Identify which installed package requires the older version of the conflicting dependency.

Solution 1: Upgrade the "Owner" of the Older Dependency Find the top-level package in your pipdeptree output that is pulling in the older, problematic version of the dependency. Try upgrading that package.

Command:

pip install --upgrade PackageD

Why it works: Upgrading PackageD might pull in a newer version of PackageC that is compatible with what PackageA needs.

Solution 2: Pinning and Forcing (Use with Caution) Sometimes, you might need to force a specific version of a dependency. This is risky because it can break the packages that expected the version you’re overriding.

Command:

pip install "PackageC==2.0" --upgrade --force-reinstall

Why it works: This command explicitly tells pip to install PackageC version 2.0 and to ignore existing installations of it. You’d then re-install the packages that were failing due to the conflict.

Cause C: setup.py vs. pyproject.toml Conflicts

Modern Python packaging uses pyproject.toml for build system specifications, while older projects might only have setup.py. Sometimes, these can interact poorly during installation, especially with complex build steps.

Diagnosis: Look for errors related to build backends, setuptools, or wheel compilation during the pip install process, not just dependency resolution.

Solution: Ensure your pip, setuptools, and wheel are up-to-date.

Command:

pip install --upgrade pip setuptools wheel

Why it works: These tools are fundamental to how pip builds and installs packages. Updates often contain fixes for compatibility issues between different packaging standards.

Cause D: Environment Manager Conflicts (e.g., Conda)

If you’re using Conda alongside pip, you can run into issues where Conda’s package manager and pip’s package manager have different ideas about installed versions. Conda often manages complex binary dependencies that pip doesn’t.

Diagnosis: Errors might occur during installation or runtime, and pip freeze might show versions that conda list does not.

Solution: Prefer Conda for installing packages where a Conda-forge equivalent exists, especially for scientific or complex libraries. Use pip only for packages not available via Conda channels.

Command:

conda install <package_name>

If you must use pip within a Conda environment:

pip install <package_name>

Why it works: Conda manages its own environment and dependencies, often resolving them more robustly for scientific packages. Mixing them requires careful attention to avoid overwriting Conda-managed files with pip-managed ones.

Cause E: Editable Installs (-e) and Lock Files

When you install packages in "editable" mode (pip install -e .) or use lock files (requirements.txt generated by pip freeze or tools like pip-tools), you’re setting specific versions. If you then try to install a new package that requires different versions of those pinned dependencies, conflicts arise.

Diagnosis: The error message will be very specific about the package you’re trying to install and the exact version conflict.

Solution: Update your lock file. If using pip-tools:

1. Edit your requirements.in file to specify the desired versions or add the new package.
2. Run pip-compile requirements.in. This regenerates requirements.txt with compatible versions.
3. Run pip install -r requirements.txt.

Why it works: pip-compile resolves the entire dependency tree based on your input file and generates a consistent set of pinned dependencies, minimizing conflicts.

4. The Last Resort: Virtual Environments

If all else fails, or if you’re working on multiple projects with different dependency needs, use virtual environments.

Command:

python -m venv myenv
source myenv/bin/activate  # On Linux/macOS
# myenv\Scripts\activate    # On Windows
pip install <package_name>

Why it works: Each virtual environment is an isolated Python installation. Installing packages in one environment does not affect any other environment or your global Python installation, making dependency management much cleaner.

Once you’ve resolved the dependency conflict, the next error you might encounter is a ModuleNotFoundError if a package’s build process failed due to a subtle incompatibility that pip didn’t flag as a dependency conflict.