Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve migration guide re: new resolver #9056

Merged
merged 6 commits into from
Oct 29, 2020
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
docs: Emphasize that pip may break existing packages
Related to #7744 .
  • Loading branch information
brainwane committed Oct 29, 2020
commit 3f4e15aef0d406a93e7a9b66280ea054938f7837
29 changes: 14 additions & 15 deletions docs/html/user_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -197,18 +197,16 @@ In practice, there are 4 common uses of Requirements files:
py -m pip freeze > requirements.txt
py -m pip install -r requirements.txt

2. Requirements files are used to force pip to properly resolve
dependencies. In versions of pip prior to 20.3, pip `doesn't have
true dependency resolution
<https://github.com/pypa/pip/issues/988>`_, but instead simply uses
the first specification it finds for a project. E.g. if ``pkg1``
requires ``pkg3>=1.0`` and ``pkg2`` requires ``pkg3>=1.0,<=2.0``,
and if ``pkg1`` is resolved first, pip will only use ``pkg3>=1.0``,
and could easily end up installing a version of ``pkg3`` that
conflicts with the needs of ``pkg2``. To solve this problem for
pip 20.2 and previous, you can place ``pkg3>=1.0,<=2.0`` (i.e. the
correct specification) into your requirements file directly along
with the other top level requirements. Like so::
2. Requirements files are used to force pip to properly resolve dependencies.
pip 20.2 and earlier `doesn't have true dependency resolution
<https://github.com/pypa/pip/issues/988>`_, but instead simply uses the first
specification it finds for a project. E.g. if ``pkg1`` requires
``pkg3>=1.0`` and ``pkg2`` requires ``pkg3>=1.0,<=2.0``, and if ``pkg1`` is
resolved first, pip will only use ``pkg3>=1.0``, and could easily end up
installing a version of ``pkg3`` that conflicts with the needs of ``pkg2``.
To solve this problem, you can place ``pkg3>=1.0,<=2.0`` (i.e. the correct
specification) into your requirements file directly along with the other top
level requirements. Like so::

pkg1
pkg2
Expand Down Expand Up @@ -1441,12 +1439,13 @@ time to fix the underlying problem in the packages, because pip will
be stricter from here on out.

This also means that, when you run a ``pip install`` command, pip only
considers the packages you are installing in that command, and may
break already-installed packages. It will not guarantee that your
considers the packages you are installing in that command, and **may
break already-installed packages**. It will not guarantee that your
environment will be consistent all the time. If you ``pip install x``
and then ``pip install y``, it's possible that the version of ``y``
you get will be different than it would be if you had run ``pip
install x y`` in a single command. We would like your thoughts on what
install x y`` in a single command. We are considering changing this
behavior (per :issue:`7744`) and would like your thoughts on what
pip's behavior should be; please answer `our survey on upgrades that
create conflicts`_.

Expand Down