McSinyx
/
pip
mirror of https://github.com/pypa/pip
1
1
Fork 0
Code Issues Releases Activity

docs: Describe --upgrade-strategy and direct requirements explicitly 

Add a brief example
This commit is contained in:
Eric Cousineau 2021-03-05 11:52:30 -05:00 committed by Tzu-ping Chung
parent 831f32e216
commit b43a8ed51e
3 changed files with 24 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/html/cli/pip_install.rst
View File

@ -1000,6 +1000,11 @@ Examples
py -m pip install --upgrade SomePackage
.. note::
This will only update ``SomePackage`` as it is a direct requirement. Any
of its dependencies (indirect requirements) will be affected by the
``--upgrade-strategy`` command.
#. Install a local project in "editable" mode. See the section on :ref:`Editable Installs <editable-installs>`.

6
docs/html/development/architecture/upgrade-options.rst
View File

@ -30,7 +30,8 @@ candidate.
``--upgrade-strategy``
This option affects which packages are allowed to be installed. It is only
relevant if ``--upgrade`` is specified. The base behaviour is to allow
relevant if ``--upgrade`` is specified (except for the ``to-satisfy-only``
option mentioned below). The base behaviour is to allow
packages specified on pip's command line to be upgraded. This option controls
what *other* packages can be upgraded:
@ -45,7 +46,8 @@ what *other* packages can be upgraded:
currently installed.
* ``to-satisfy-only`` (**undocumented**) - packages are not upgraded (not
even direct requirements) unless the currently installed version fails to
satisfy a requirement (either explicitly specified or a dependency).
satisfy a requirement (either explicitly specified or a dependency). This
is actually the "default" strategy when ``--upgrade`` is not set.
``--force-reinstall``

15
docs/html/user_guide.rst
View File

@ -825,6 +825,21 @@ strategies supported:
The default strategy is ``only-if-needed``. This was changed in pip 10.0 due to
the breaking nature of ``eager`` when upgrading conflicting dependencies.
It is important to note that ``--upgrade`` affects *direct requirements* (e.g.
those specified on the command-line or via a requirements file) while
``--upgrade-strategy`` affects *indirect requirements* (dependencies of direct
requirements).
As an example, say ``SomePackage`` has a dependency, ``SomeDependency``, and
both of them are already installed but are not the latest avaialable versions:
- ``pip install SomePackage``: will not upgrade the existing ``SomePackage`` or
``SomeDependency``.
- ``pip install --upgrade SomePackage``: will upgrade ``SomePackage``, but not
``SomeDependency`` (unless a minimum requirement is not met).
- ``pip install --upgrade SomePackage --upgrade-strategy=eager``: upgrades both
``SomePackage`` and ``SomeDependency``.
As an historic note, an earlier "fix" for getting the ``only-if-needed``
behaviour was: