Allow pip to complete its backtracking¶

In most cases, pip will complete the backtracking process successfully.This could take a very long time to complete, so this may not be yourpreferred option.

However, it is a possible that pip will not be able to find a set ofcompatible versions. For this, pip will try every possible combination thatit needs to and determine that there is no compatible set.

If you’d prefer not to wait, you can interrupt pip (Ctrl+c) and try thestrategies listed below.

Reduce the number of versions pip is trying to use¶

It is usually a good idea to add constraints the package(s) that pip is backtracking on (e.g. in the above example -cup).

You could try something like:

$python-mpipinstalltea"cup >= 3.13"

$python-mpipinstalltea"cup >= 3.13"

C:> py -m pip install tea"cup >= 3.13"

This will reduce the number of versions ofcup it tries, andpossibly reduce the time pip takes to install.

There is a possibility that the addition constraint is incorrect. When thishappens, the reduced search space makes it easier for pip to more quicklydetermine what caused the conflict and present that to the user. It could alsoresult in pip backtracking on a different package due to some other conflict.

Use constraint files or lockfiles¶

This option is a progression of the previous section. It requires users to knowhow to inspect:

• the packages they’re trying to install

• the package release frequency and compatibility policies

• their release notes and changelogs from past versions

During deployment, you can create a lockfile stating the exact package andversion number for each dependency of that package. You can create thiswithpip-tools.

This means the “work” is done once during development process, and thuswill avoid performing dependency resolution during deployment.

Understanding your error message¶

When you get aResolutionImpossible error, you might see somethinglike this:

$python-mpipinstallpackage_coffee==0.44.1package_tea==4.3.0[regular pip output]ERROR: Cannot install package_coffee==0.44.1 and package_tea==4.3.0 because these package versions have conflicting dependencies.The conflict is caused by:    package_coffee 0.44.1 depends on package_water<3.0.0,>=2.4.2    package_tea 4.3.0 depends on package_water==2.3.1

$python-mpipinstallpackage_coffee==0.44.1package_tea==4.3.0[regular pip output]ERROR: Cannot install package_coffee==0.44.1 and package_tea==4.3.0 because these package versions have conflicting dependencies.The conflict is caused by:    package_coffee 0.44.1 depends on package_water<3.0.0,>=2.4.2    package_tea 4.3.0 depends on package_water==2.3.1

C:> py -m pip install package_coffee==0.44.1 package_tea==4.3.0[regular pip output]ERROR: Cannot install package_coffee==0.44.1 and package_tea==4.3.0 because these package versions have conflicting dependencies.The conflict is caused by:    package_coffee 0.44.1 depends on package_water<3.0.0,>=2.4.2    package_tea 4.3.0 depends on package_water==2.3.1

In this example, pip cannot install the packages you have requested,because they each depend on different versions of the same package(package_water):

• package_coffee version0.44.1 depends on a version ofpackage_water that is less than3.0.0 but greater than or equal to2.4.2

• package_tea version4.3.0 depends on version2.3.1 ofpackage_water

Sometimes these messages are straightforward to read, because they usecommonly understood comparison operators to specify the required version(e.g.< or>).

However, Python packaging also supports some more complex ways forspecifying package versions (e.g.~= or*):

¹ Compatible versions are higher versions that only differ in the final segment.~=3.1.2 is equivalent to>=3.1.2,==3.1.*.~=3.1 is equivalent to>=3.1,==3.*.

The detailed specification of supported comparison operators can befound inPEP 440.

Possible solutions¶

The solution to your error will depend on your individual use case. Hereare some things to try:

$python-mpipinstallpackage_coffee==0.44.1package_tea

$python-mpipinstallpackage_coffee==0.44.1package_tea

C:> py -m pip install package_coffee==0.44.1 package_tea

Specify Reasonable Lower Bounds¶

By setting a higher lower bound for your dependencies, you narrow the searchspace. This excludes older versions that might trigger excessive backtracking.For example:

$python-mpipinstall"package_coffee>=0.44.0""package_tea>=4.0.0"

$python-mpipinstall"package_coffee>=0.44.0""package_tea>=4.0.0"

C:> py -m pip install"package_coffee>=0.44.0""package_tea>=4.0.0"

Use the--upgrade Flag¶

The--upgrade flag directs pip to ignore already installed versions andsearch for the latest versions that meet your requirements. This can helpavoid unnecessary resolution paths:

$python-mpipinstall--upgradepackage_coffeepackage_tea

$python-mpipinstall--upgradepackage_coffeepackage_tea

C:> py -m pip install --upgrade package_coffee package_tea

Utilize Constraint Files¶

If you need to impose additional version restrictions on transitivedependencies (dependencies of dependencies), consider using a constraintfile. A constraint file specifies version limits for packages that areindirectly required. For example:

# constraints.txtindirect_dependency>=2.0.0

Then install your packages with:

$python-mpipinstall--constraintconstraints.txtpackage_coffeepackage_tea

$python-mpipinstall--constraintconstraints.txtpackage_coffeepackage_tea

C:> py -m pip install --constraint constraints.txt package_coffee package_tea

Use Upper Bounds Sparingly¶

Although upper bounds are generally discouraged because they can complicatedependency management, they may be necessary when certain versions are knownto cause conflicts. Use them cautiously—for example:

$python-mpipinstall"package_coffee>=0.44.0,<1.0.0""package_tea>=4.0.0"

$python-mpipinstall"package_coffee>=0.44.0,<1.0.0""package_tea>=4.0.0"

C:> py -m pip install"package_coffee>=0.44.0,<1.0.0""package_tea>=4.0.0"

Report ResolutionTooDeep Errors¶

If you encounter aResolutionTooDeep error consider reporting it, to helpthe pip team have real world examples to test against, at the dedicatedpip issue.