Options that control the installation process#
When installing packages, pip chooses a distribution file, and installs it in the user’s environment. There are many choices (which are still evolving) involved in deciding which file to install, and these are controlled by a variety of options.
This section of the documentation needs to be updated per Changes to the pip dependency resolver in 20.3 (2020).
Controlling what gets installed#
These options directly affect how the resolver uses the list of available distribution files to decide which one to install. So these modify the resolution algorithm itself, rather than the input to that algorithm.
Allow installing a newer version of an installed package. In principle, this
option actually affects “what gets considered”, in the sense that it allows
the resolver to see other versions of installed packages. Without
--upgrade, the resolver will only see the installed version as a
This option affects which packages are allowed to be installed. It is only
--upgrade is specified (except for the
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:
eager- all packages will be upgraded to the latest possible version. It should be noted here that pip’s current resolution algorithm isn’t even aware of packages other than those specified on the command line, and those identified as dependencies. This may or may not be true of the new resolver.
only-if-needed- packages are only upgraded if they are named in the pip command or a requirement file (i.e, they are direct requirements), or an upgraded parent needs a later version of the dependency than is currently installed.
to-satisfy-only(undocumented, please avoid) - packages are not upgraded (not even direct requirements) unless the currently installed version fails to satisfy a requirement (either explicitly specified or a dependency).
This is actually the “default” upgrade strategy when
--upgradeis not set, i.e.
pip install AlreadyInstalledand
pip install --upgrade --upgrade-strategy=to-satisfy-only AlreadyInstalledyield the same behavior.
Doesn’t affect resolution, but if the resolved result is the same as what is
currently installed, uninstall and reinstall it rather than leaving the
current version in place. This occurs even if
--upgrade is not set.
Act as if the currently installed version isn’t there - so don’t care about
--upgrade, and don’t uninstall before (re-)installing.
Controlling what gets considered#
These options affect the list of distribution files that the resolver will consider as candidates for installation. As such, they affect the data that the resolver has to work with, rather than influencing what pip does with the resolution result.
Source vs Binary
Wheel tag specification
Controlling dependency data#
These options control what dependency data the resolver sees for any given
package (or, in the case of
--python-version, the environment information
the resolver uses to check the dependency).
These need further investigation. They affect the install process, but not necessarily resolution or what gets installed.