Skip to content

Commit 3f4e15a

Browse files
committed
docs: Emphasize that pip may break existing packages
Related to #7744 .
1 parent fbcdeca commit 3f4e15a

File tree

1 file changed

+14
-15
lines changed

1 file changed

+14
-15
lines changed

docs/html/user_guide.rst

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -197,18 +197,16 @@ In practice, there are 4 common uses of Requirements files:
197197
py -m pip freeze > requirements.txt
198198
py -m pip install -r requirements.txt
199199
200-
2. Requirements files are used to force pip to properly resolve
201-
dependencies. In versions of pip prior to 20.3, pip `doesn't have
202-
true dependency resolution
203-
<https://github.com/pypa/pip/issues/988>`_, but instead simply uses
204-
the first specification it finds for a project. E.g. if ``pkg1``
205-
requires ``pkg3>=1.0`` and ``pkg2`` requires ``pkg3>=1.0,<=2.0``,
206-
and if ``pkg1`` is resolved first, pip will only use ``pkg3>=1.0``,
207-
and could easily end up installing a version of ``pkg3`` that
208-
conflicts with the needs of ``pkg2``. To solve this problem for
209-
pip 20.2 and previous, you can place ``pkg3>=1.0,<=2.0`` (i.e. the
210-
correct specification) into your requirements file directly along
211-
with the other top level requirements. Like so::
200+
2. Requirements files are used to force pip to properly resolve dependencies.
201+
pip 20.2 and earlier `doesn't have true dependency resolution
202+
<https://github.com/pypa/pip/issues/988>`_, but instead simply uses the first
203+
specification it finds for a project. E.g. if ``pkg1`` requires
204+
``pkg3>=1.0`` and ``pkg2`` requires ``pkg3>=1.0,<=2.0``, and if ``pkg1`` is
205+
resolved first, pip will only use ``pkg3>=1.0``, and could easily end up
206+
installing a version of ``pkg3`` that conflicts with the needs of ``pkg2``.
207+
To solve this problem, you can place ``pkg3>=1.0,<=2.0`` (i.e. the correct
208+
specification) into your requirements file directly along with the other top
209+
level requirements. Like so::
212210

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

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

0 commit comments

Comments
 (0)