Skip to content

Update documentation to mention upgrade-strategy #4232

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Jan 27, 2017
Merged

Update documentation to mention upgrade-strategy #4232

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
34 changes: 14 additions & 20 deletions docs/user_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -476,32 +476,26 @@ $ pip install --no-index --find-links=DIR -r requirements.txt
"Only if needed" Recursive Upgrade
**********************************

``pip install --upgrade`` is currently written to perform an eager recursive
upgrade, i.e. it upgrades all dependencies regardless of whether they still
satisfy the new parent requirements.
``pip install --upgrade`` now has a ``--upgrade-strategy`` option which
controls how pip handles upgrading of dependencies. There are 2 upgrade
strategies supported:

E.g. supposing:
- ``eager``: upgrades all dependencies regardless of whether they still satisfy
the new parent requirements
- ``only-if-needed``: upgrades a dependency only if it does not satisfy the new
parent requirements

Currently, the default strategy is ``eager``, which was the strategy prior to
the ``--upgrade-strategy`` option being added.

* `SomePackage-1.0` requires `AnotherPackage>=1.0`
* `SomePackage-2.0` requires `AnotherPackage>=1.0` and `OneMorePackage==1.0`
* `SomePackage-1.0` and `AnotherPackage-1.0` are currently installed
* `SomePackage-2.0` and `AnotherPackage-2.0` are the latest versions available on PyPI.

Running ``pip install --upgrade SomePackage`` would upgrade `SomePackage` *and*
`AnotherPackage` despite `AnotherPackage` already being satisfied.

pip doesn't currently have an option to do an "only if needed" recursive
upgrade, but you can achieve it using these 2 steps::
As an historic note, an earlier "fix" for getting the ``only-if-needed``
behaviour was::

pip install --upgrade --no-deps SomePackage
pip install SomePackage

The first line will upgrade `SomePackage`, but not dependencies like
`AnotherPackage`. The 2nd line will fill in new dependencies like
`OneMorePackage`.

See :issue:`59` for a plan of making "only if needed" recursive the default
behavior for a new ``pip upgrade`` command.
A proposal for an ``upgrade-all`` command is being considered as a safer
alternative to the behaviour of eager upgrading.


User Installs
Expand Down