From b7c3503a342ba52b3e782a4a3373f8b31e855e4a Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Mon, 26 Oct 2020 15:44:15 -0400 Subject: [PATCH] Add note about install/upgrade behavior to docs Towards #8115. --- docs/html/development/architecture/upgrade-options.rst | 10 +++++++--- docs/html/reference/pip_install.rst | 3 +++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/html/development/architecture/upgrade-options.rst b/docs/html/development/architecture/upgrade-options.rst index 36e34c71ee9..0527101f8c6 100644 --- a/docs/html/development/architecture/upgrade-options.rst +++ b/docs/html/development/architecture/upgrade-options.rst @@ -2,9 +2,10 @@ 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 involved in deciding which file -to install, and these are controlled by a variety of options. +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. .. note:: @@ -122,3 +123,6 @@ necessarily resolution or what gets installed. ``--constraint`` ``--editable `` + + +.. _still evolving: https://github.com/pypa/pip/issues/8115 diff --git a/docs/html/reference/pip_install.rst b/docs/html/reference/pip_install.rst index 7d6b5471a2b..be974dacf61 100644 --- a/docs/html/reference/pip_install.rst +++ b/docs/html/reference/pip_install.rst @@ -36,6 +36,9 @@ pip install has several stages: 3. Build wheels. All the dependencies that can be are built into wheels. 4. Install the packages (and uninstall anything being upgraded/replaced). +Note that ``pip install`` prefers to leave the installed version as-is +unless ``--upgrade`` is specified. + Argument Handling -----------------