Skip to content

Commit d7c3306

Browse files
pradyunsgpradyunsg
committed
Move section on dependency conflicts to dependency resolution topic
1 parent da6239d commit d7c3306

File tree

2 files changed

+156
-209
lines changed

2 files changed

+156
-209
lines changed

‎docs/html/topics/dependency-resolution.md

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,3 +160,158 @@ with `pip-tools <https://github.com/jazzband/pip-tools/>`\_\_.
160160

161161
This means the "work" is done once during development process, and thus
162162
will avoid performing dependency resolution during deployment.
163+
164+
## Dealing with dependency conflicts
165+
166+
This section provides practical suggestions to pip users who encounter
167+
a `ResolutionImpossible` error, where pip cannot install their specified
168+
packages due to conflicting dependencies.
169+
170+
### Understanding your error message
171+
172+
When you get a `ResolutionImpossible` error, you might see something
173+
like this:
174+
175+
```{pip-cli}
176+
$ pip install "pytest < 4.6" pytest-cov==2.12.1
177+
[regular pip output]
178+
ERROR: Cannot install pytest-cov==2.12.1 and pytest<4.6 because these package versions have conflicting dependencies.
179+
180+
The conflict is caused by:
181+
The user requested pytest<4.6
182+
pytest-cov 2.12.1 depends on pytest>=4.6
183+
```
184+
185+
In this example, pip cannot install the packages requested because they are
186+
asking for conflicting versions of pytest.
187+
188+
- `pytest-cov` version `2.12.1`, requires `pytest` with a version or equal to
189+
`4.6`.
190+
- `package_tea` version `4.3.0` depends on version `2.3.1` of
191+
`package_water`
192+
193+
Sometimes these messages are straightforward to read, because they use
194+
commonly understood comparison operators to specify the required version
195+
(e.g. `<` or `>`).
196+
197+
However, Python packaging also supports some more complex ways for
198+
specifying package versions (e.g. `~=` or `*`):
199+
200+
| Operator | Description | Example |
201+
| -------- | -------------------------------------------------------------- | --------------------------------------------------- |
202+
| `>` | Any version greater than the specified version. | `>3.1`: any version greater than `3.1`. |
203+
| `<` | Any version less than the specified version. | `<3.1`: any version less than `3.1`. |
204+
| `<=` | Any version less than or equal to the specified version. | `<=3.1`: any version less than or equal to `3.1`. |
205+
| `>=` | Any version greater than or equal to the specified version. | `>=3.1`: version `3.1` and greater. |
206+
| `==` | Exactly the specified version. | `==3.1`: only `3.1`. |
207+
| `!=` | Any version not equal to the specified version. | `!=3.1`: any version other than `3.1`. |
208+
| `~=` | Any compatible{sup}`1` version. | `~=3.1`: any version compatible{sup}`1` with `3.1`. |
209+
| `*` | Can be used at the end of a version number to represent _all_. | `==3.1.*`: any version that starts with `3.1`. |
210+
211+
{sup}`1` Compatible versions are higher versions that only differ in the final segment.
212+
`~=3.1.2` is equivalent to `>=3.1.2, ==3.1.*`. `~=3.1` is equivalent to `>=3.1, ==3.*`.
213+
214+
The detailed specification of supported comparison operators can be
215+
found in {pep}`440`.
216+
217+
### Possible solutions
218+
219+
The solution to your error will depend on your individual use case. Here
220+
are some things to try:
221+
222+
#### Audit your top level requirements
223+
224+
As a first step, it is useful to audit your project and remove any
225+
unnecessary or out of date requirements (e.g. from your `setup.py` or
226+
`requirements.txt` files). Removing these can significantly reduce the
227+
complexity of your dependency tree, thereby reducing opportunities for
228+
conflicts to occur.
229+
230+
#### Loosen your top level requirements
231+
232+
Sometimes the packages that you have asked pip to install are
233+
incompatible because you have been too strict when you specified the
234+
package version.
235+
236+
In our first example both `package_coffee` and `package_tea` have been
237+
_pinned_ to use specific versions
238+
(`package_coffee==0.44.1b0 package_tea==4.3.0`).
239+
240+
To find a version of both `package_coffee` and `package_tea` that depend on
241+
the same version of `package_water`, you might consider:
242+
243+
- Loosening the range of packages that you are prepared to install
244+
(e.g. `pip install "package_coffee>0.44.*" "package_tea>4.0.0"`)
245+
- Asking pip to install _any_ version of `package_coffee` and `package_tea`
246+
by removing the version specifiers altogether (e.g.
247+
`pip install package_coffee package_tea`)
248+
249+
In the second case, pip will automatically find a version of both
250+
`package_coffee` and `package_tea` that depend on the same version of
251+
`package_water`, installing:
252+
253+
- `package_coffee 0.46.0b0`, which depends on `package_water 2.6.1`
254+
- `package_tea 4.3.0` which _also_ depends on `package_water 2.6.1`
255+
256+
If you want to prioritize one package over another, you can add version
257+
specifiers to _only_ the more important package:
258+
259+
```{pip-cli}
260+
$ pip install package_coffee==0.44.1b0 package_tea
261+
```
262+
263+
This will result in:
264+
265+
- `package_coffee 0.44.1b0`, which depends on `package_water 2.6.1`
266+
- `package_tea 4.1.3` which also depends on `package_water 2.6.1`
267+
268+
Now that you have resolved the issue, you can repin the compatible
269+
package versions as required.
270+
271+
#### Loosen the requirements of your dependencies
272+
273+
Assuming that you cannot resolve the conflict by loosening the version
274+
of the package you require (as above), you can try to fix the issue on
275+
your _dependency_ by:
276+
277+
- Requesting that the package maintainers loosen _their_ dependencies
278+
- Forking the package and loosening the dependencies yourself
279+
280+
:::{warning}
281+
If you choose to fork the package yourself, you are _opting out_ of
282+
any support provided by the package maintainers. Proceed at your own risk!
283+
:::
284+
285+
#### All requirements are appropriate, but a solution does not exist
286+
287+
Sometimes it's simply impossible to find a combination of package
288+
versions that do not conflict. Welcome to [dependency hell].
289+
290+
In this situation, you could consider:
291+
292+
- Using an alternative package, if that is acceptable for your project.
293+
See [Awesome Python] for similar packages.
294+
- Refactoring your project to reduce the number of dependencies (for
295+
example, by breaking up a monolithic code base into smaller pieces).
296+
297+
### Getting help
298+
299+
If none of the suggestions above work for you, we recommend that you ask
300+
for help on:
301+
302+
- [Python user Discourse](https://discuss.python.org/c/users/7)
303+
- [Python user forums](https://www.python.org/community/forums/)
304+
- [Python developers Slack channel](https://pythondev.slack.com/)
305+
- [Python IRC](https://www.python.org/community/irc/)
306+
- [Stack Overflow](https://stackoverflow.com/questions/tagged/python)
307+
308+
See ["How do I ask a good question?"] for tips on asking for help.
309+
310+
Unfortunately, **the pip team cannot provide support for individual
311+
dependency conflict errors**. Please _only_ open a ticket on
312+
[pip's issue tracker](https://github.com/pypa/pip/issues) if you believe
313+
that your problem has exposed a bug in pip.
314+
315+
["how do i ask a good question?"]: https://stackoverflow.com/help/how-to-ask
316+
[awesome python]: https://python.libhunt.com/
317+
[dependency hell]: https://en.wikipedia.org/wiki/Dependency_hell

‎docs/html/user_guide.rst

Lines changed: 1 addition & 209 deletions
Original file line numberDiff line numberDiff line change
@@ -789,215 +789,7 @@ This is now covered in :doc:`../topics/repeatable-installs`.
789789
Fixing conflicting dependencies
790790
===============================
791791

792-
The purpose of this section of documentation is to provide practical suggestions to
793-
pip users who encounter an error where pip cannot install their
794-
specified packages due to conflicting dependencies (a
795-
``ResolutionImpossible`` error).
796-
797-
This documentation is specific to the new resolver, which is the
798-
default behavior in pip 20.3 and later. If you are using pip 20.2, you
799-
can invoke the new resolver by using the flag
800-
``--use-feature=2020-resolver``.
801-
802-
Understanding your error message
803-
--------------------------------
804-
805-
When you get a ``ResolutionImpossible`` error, you might see something
806-
like this:
807-
808-
.. tab:: Unix/macOS
809-
810-
.. code-block:: shell
811-
812-
python -m pip install package_coffee==0.44.1 package_tea==4.3.0
813-
814-
.. tab:: Windows
815-
816-
.. code-block:: shell
817-
818-
py -m pip install package_coffee==0.44.1 package_tea==4.3.0
819-
820-
::
821-
822-
Due to conflicting dependencies pip cannot install
823-
package_coffee and package_tea:
824-
- package_coffee depends on package_water<3.0.0,>=2.4.2
825-
- package_tea depends on package_water==2.3.1
826-
827-
In this example, pip cannot install the packages you have requested,
828-
because they each depend on different versions of the same package
829-
(``package_water``):
830-
831-
- ``package_coffee`` version ``0.44.1`` depends on a version of
832-
``package_water`` that is less than ``3.0.0`` but greater than or equal to
833-
``2.4.2``
834-
- ``package_tea`` version ``4.3.0`` depends on version ``2.3.1`` of
835-
``package_water``
836-
837-
Sometimes these messages are straightforward to read, because they use
838-
commonly understood comparison operators to specify the required version
839-
(e.g. ``<`` or ``>``).
840-
841-
However, Python packaging also supports some more complex ways for
842-
specifying package versions (e.g. ``~=`` or ``*``):
843-
844-
+----------+---------------------------------+--------------------------------+
845-
| Operator | Description | Example |
846-
+==========+=================================+================================+
847-
| ``>`` | Any version greater than | ``>3.1``: any version |
848-
| | the specified version. | greater than ``3.1``. |
849-
+----------+---------------------------------+--------------------------------+
850-
| ``<`` | Any version less than | ``<3.1``: any version |
851-
| | the specified version. | less than ``3.1``. |
852-
+----------+---------------------------------+--------------------------------+
853-
| ``<=`` | Any version less than or | ``<=3.1``: any version |
854-
| | equal to the specified version. | less than or equal to ``3.1``. |
855-
+----------+---------------------------------+--------------------------------+
856-
| ``>=`` | Any version greater than or | ``>=3.1``: |
857-
| | equal to the specified version. | version ``3.1`` and greater. |
858-
+----------+---------------------------------+--------------------------------+
859-
| ``==`` | Exactly the specified version. | ``==3.1``: only ``3.1``. |
860-
+----------+---------------------------------+--------------------------------+
861-
| ``!=`` | Any version not equal | ``!=3.1``: any version |
862-
| | to the specified version. | other than ``3.1``. |
863-
+----------+---------------------------------+--------------------------------+
864-
| ``~=`` | Any compatible release. | ``~=3.1``: version ``3.1`` |
865-
| | Compatible releases are | or later, but not |
866-
| | releases that are within the | version ``4.0`` or later. |
867-
| | same major or minor version, | ``~=3.1.2``: version ``3.1.2`` |
868-
| | assuming the package author | or later, but not |
869-
| | is using semantic versioning. | version ``3.2.0`` or later. |
870-
+----------+---------------------------------+--------------------------------+
871-
| ``*`` | Can be used at the end of | ``==3.1.*``: any version |
872-
| | a version number to represent | that starts with ``3.1``. |
873-
| | *all*, | Equivalent to ``~=3.1.0``. |
874-
+----------+---------------------------------+--------------------------------+
875-
876-
The detailed specification of supported comparison operators can be
877-
found in :pep:`440`.
878-
879-
Possible solutions
880-
------------------
881-
882-
The solution to your error will depend on your individual use case. Here
883-
are some things to try:
884-
885-
1. Audit your top level requirements
886-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
887-
888-
As a first step it is useful to audit your project and remove any
889-
unnecessary or out of date requirements (e.g. from your ``setup.py`` or
890-
``requirements.txt`` files). Removing these can significantly reduce the
891-
complexity of your dependency tree, thereby reducing opportunities for
892-
conflicts to occur.
893-
894-
2. Loosen your top level requirements
895-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
896-
897-
Sometimes the packages that you have asked pip to install are
898-
incompatible because you have been too strict when you specified the
899-
package version.
900-
901-
In our first example both ``package_coffee`` and ``package_tea`` have been
902-
*pinned* to use specific versions
903-
(``package_coffee==0.44.1b0 package_tea==4.3.0``).
904-
905-
To find a version of both ``package_coffee`` and ``package_tea`` that depend on
906-
the same version of ``package_water``, you might consider:
907-
908-
- Loosening the range of packages that you are prepared to install
909-
(e.g. ``pip install "package_coffee>0.44.*" "package_tea>4.0.0"``)
910-
- Asking pip to install *any* version of ``package_coffee`` and ``package_tea``
911-
by removing the version specifiers altogether (e.g.
912-
``python -m pip install package_coffee package_tea``)
913-
914-
In the second case, pip will automatically find a version of both
915-
``package_coffee`` and ``package_tea`` that depend on the same version of
916-
``package_water``, installing:
917-
918-
- ``package_coffee 0.46.0b0``, which depends on ``package_water 2.6.1``
919-
- ``package_tea 4.3.0`` which *also* depends on ``package_water 2.6.1``
920-
921-
If you want to prioritize one package over another, you can add version
922-
specifiers to *only* the more important package:
923-
924-
.. tab:: Unix/macOS
925-
926-
.. code-block:: shell
927-
928-
python -m pip install package_coffee==0.44.1b0 package_tea
929-
930-
.. tab:: Windows
931-
932-
.. code-block:: shell
933-
934-
py -m pip install package_coffee==0.44.1b0 package_tea
935-
936-
This will result in:
937-
938-
- ``package_coffee 0.44.1b0``, which depends on ``package_water 2.6.1``
939-
- ``package_tea 4.1.3`` which also depends on ``package_water 2.6.1``
940-
941-
Now that you have resolved the issue, you can repin the compatible
942-
package versions as required.
943-
944-
3. Loosen the requirements of your dependencies
945-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
946-
947-
Assuming that you cannot resolve the conflict by loosening the version
948-
of the package you require (as above), you can try to fix the issue on
949-
your *dependency* by:
950-
951-
- Requesting that the package maintainers loosen *their* dependencies
952-
- Forking the package and loosening the dependencies yourself
953-
954-
.. warning::
955-
956-
If you choose to fork the package yourself, you are *opting out* of
957-
any support provided by the package maintainers. Proceed at your own risk!
958-
959-
4. All requirements are loose, but a solution does not exist
960-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
961-
962-
Sometimes it's simply impossible to find a combination of package
963-
versions that do not conflict. Welcome to `dependency hell`_.
964-
965-
In this situation, you could consider:
966-
967-
- Using an alternative package, if that is acceptable for your project.
968-
See `Awesome Python`_ for similar packages.
969-
- Refactoring your project to reduce the number of dependencies (for
970-
example, by breaking up a monolithic code base into smaller pieces)
971-
972-
.. _`Getting help`:
973-
974-
Getting help
975-
------------
976-
977-
If none of the suggestions above work for you, we recommend that you ask
978-
for help on:
979-
980-
- `Python user Discourse`_
981-
- `Python user forums`_
982-
- `Python developers Slack channel`_
983-
- `Python IRC`_
984-
- `Stack Overflow`_
985-
986-
See `"How do I ask a good question?"`_ for tips on asking for help.
987-
988-
Unfortunately, **the pip team cannot provide support for individual
989-
dependency conflict errors**. Please *only* open a ticket on the `pip
990-
issue tracker`_ if you believe that your problem has exposed a bug in pip.
991-
992-
.. _dependency hell: https://en.wikipedia.org/wiki/Dependency_hell
993-
.. _Awesome Python: https://python.libhunt.com/
994-
.. _Python user Discourse: https://discuss.python.org/c/users/7
995-
.. _Python user forums: https://www.python.org/community/forums/
996-
.. _Python developers Slack channel: https://pythondev.slack.com/
997-
.. _Python IRC: https://www.python.org/community/irc/
998-
.. _Stack Overflow: https://stackoverflow.com/questions/tagged/python
999-
.. _"How do I ask a good question?": https://stackoverflow.com/help/how-to-ask
1000-
.. _pip issue tracker: https://github.com/pypa/pip/issues
792+
This is now covered in :doc:`../topics/dependency-resolution`.
1001793

1002794
.. _`Using pip from your program`:
1003795

0 commit comments

Comments
 (0)