mirror of
https://github.com/pypa/pip
synced 2023-12-13 21:30:23 +01:00
Merge pull request #9056 from brainwane/docs-migration-guide-details
Improve migration guide re: new resolver
This commit is contained in:
commit
8daece5277
4 changed files with 50 additions and 20 deletions
|
@ -2,9 +2,10 @@
|
||||||
Options that control the installation process
|
Options that control the installation process
|
||||||
=============================================
|
=============================================
|
||||||
|
|
||||||
When installing packages, pip chooses a distribution file, and installs it in
|
When installing packages, pip chooses a distribution file, and
|
||||||
the user's environment. There are many choices involved in deciding which file
|
installs it in the user's environment. There are many choices (which
|
||||||
to install, and these are controlled by a variety of options.
|
are `still evolving`_) involved in deciding which file to install, and
|
||||||
|
these are controlled by a variety of options.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
|
@ -122,3 +123,6 @@ necessarily resolution or what gets installed.
|
||||||
``--constraint``
|
``--constraint``
|
||||||
|
|
||||||
``--editable <LOCATION>``
|
``--editable <LOCATION>``
|
||||||
|
|
||||||
|
|
||||||
|
.. _still evolving: https://github.com/pypa/pip/issues/8115
|
||||||
|
|
|
@ -36,6 +36,9 @@ pip install has several stages:
|
||||||
3. Build wheels. All the dependencies that can be are built into wheels.
|
3. Build wheels. All the dependencies that can be are built into wheels.
|
||||||
4. Install the packages (and uninstall anything being upgraded/replaced).
|
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
|
Argument Handling
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
|
|
|
@ -197,18 +197,16 @@ In practice, there are 4 common uses of Requirements files:
|
||||||
py -m pip freeze > requirements.txt
|
py -m pip freeze > requirements.txt
|
||||||
py -m pip install -r requirements.txt
|
py -m pip install -r requirements.txt
|
||||||
|
|
||||||
2. Requirements files are used to force pip to properly resolve
|
2. Requirements files are used to force pip to properly resolve dependencies.
|
||||||
dependencies. In versions of pip prior to 20.3, pip `doesn't have
|
pip 20.2 and earlier `doesn't have true dependency resolution
|
||||||
true dependency resolution
|
<https://github.com/pypa/pip/issues/988>`_, but instead simply uses the first
|
||||||
<https://github.com/pypa/pip/issues/988>`_, but instead simply uses
|
specification it finds for a project. E.g. if ``pkg1`` requires
|
||||||
the first specification it finds for a project. E.g. if ``pkg1``
|
``pkg3>=1.0`` and ``pkg2`` requires ``pkg3>=1.0,<=2.0``, and if ``pkg1`` is
|
||||||
requires ``pkg3>=1.0`` and ``pkg2`` requires ``pkg3>=1.0,<=2.0``,
|
resolved first, pip will only use ``pkg3>=1.0``, and could easily end up
|
||||||
and if ``pkg1`` is resolved first, pip will only use ``pkg3>=1.0``,
|
installing a version of ``pkg3`` that conflicts with the needs of ``pkg2``.
|
||||||
and could easily end up installing a version of ``pkg3`` that
|
To solve this problem, you can place ``pkg3>=1.0,<=2.0`` (i.e. the correct
|
||||||
conflicts with the needs of ``pkg2``. To solve this problem for
|
specification) into your requirements file directly along with the other top
|
||||||
pip 20.2 and previous, you can place ``pkg3>=1.0,<=2.0`` (i.e. the
|
level requirements. Like so::
|
||||||
correct specification) into your requirements file directly along
|
|
||||||
with the other top level requirements. Like so::
|
|
||||||
|
|
||||||
pkg1
|
pkg1
|
||||||
pkg2
|
pkg2
|
||||||
|
@ -291,7 +289,11 @@ organisation and use that everywhere. If the thing being installed requires
|
||||||
"helloworld" to be installed, your fixed version specified in your constraints
|
"helloworld" to be installed, your fixed version specified in your constraints
|
||||||
file will be used.
|
file will be used.
|
||||||
|
|
||||||
Constraints file support was added in pip 7.1.
|
Constraints file support was added in pip 7.1. In :ref:`Resolver
|
||||||
|
changes 2020` we did a fairly comprehensive overhaul, removing several
|
||||||
|
undocumented and unsupported quirks from the previous implementation,
|
||||||
|
and stripped constraints files down to being purely a way to specify
|
||||||
|
global (version) limits for packages.
|
||||||
|
|
||||||
.. _`Installing from Wheels`:
|
.. _`Installing from Wheels`:
|
||||||
|
|
||||||
|
@ -1437,17 +1439,37 @@ time to fix the underlying problem in the packages, because pip will
|
||||||
be stricter from here on out.
|
be stricter from here on out.
|
||||||
|
|
||||||
This also means that, when you run a ``pip install`` command, pip only
|
This also means that, when you run a ``pip install`` command, pip only
|
||||||
considers the packages you are installing in that command, and may
|
considers the packages you are installing in that command, and **may
|
||||||
break already-installed packages. It will not guarantee that your
|
break already-installed packages**. It will not guarantee that your
|
||||||
environment will be consistent all the time. If you ``pip install x``
|
environment will be consistent all the time. If you ``pip install x``
|
||||||
and then ``pip install y``, it's possible that the version of ``y``
|
and then ``pip install y``, it's possible that the version of ``y``
|
||||||
you get will be different than it would be if you had run ``pip
|
you get will be different than it would be if you had run ``pip
|
||||||
install x y`` in a single command. We would like your thoughts on what
|
install x y`` in a single command. We are considering changing this
|
||||||
|
behavior (per :issue:`7744`) and would like your thoughts on what
|
||||||
pip's behavior should be; please answer `our survey on upgrades that
|
pip's behavior should be; please answer `our survey on upgrades that
|
||||||
create conflicts`_.
|
create conflicts`_.
|
||||||
|
|
||||||
We are also changing our support for :ref:`Constraints Files`:
|
We are also changing our support for :ref:`Constraints Files`,
|
||||||
|
editable installs, and related functionality. We did a fairly
|
||||||
|
comprehensive overhaul and stripped constraints files down to being
|
||||||
|
purely a way to specify global (version) limits for packages, and so
|
||||||
|
some combinations that used to be allowed will now cause
|
||||||
|
errors. Specifically:
|
||||||
|
|
||||||
|
* Constraints don't override the existing requirements; they simply
|
||||||
|
constrain what versions are visible as input to the resolver (see
|
||||||
|
:issue:`9020`)
|
||||||
|
* Providing an editable requirement (``-e .``) does not cause pip to
|
||||||
|
ignore version specifiers or constraints (see :issue:`8076`), and if
|
||||||
|
you have a conflict between a pinned requirement and a local
|
||||||
|
directory then pip will indicate that it cannot find a version
|
||||||
|
satisfying both (see :issue:`8307`)
|
||||||
|
* Hash-checking mode requires that all requirements are specified as a
|
||||||
|
``==`` match on a version and may not work well in combination with
|
||||||
|
constraints (see :issue:`9020` and :issue:`8792`)
|
||||||
|
* If necessary to satisfy constraints, pip will happily reinstall
|
||||||
|
packages, upgrading or downgrading, without needing any additional
|
||||||
|
command-line options (see :issue:`8115` and :doc:`development/architecture/upgrade-options`)
|
||||||
* Unnamed requirements are not allowed as constraints (see :issue:`6628` and :issue:`8210`)
|
* Unnamed requirements are not allowed as constraints (see :issue:`6628` and :issue:`8210`)
|
||||||
* Links are not allowed as constraints (see :issue:`8253`)
|
* Links are not allowed as constraints (see :issue:`8253`)
|
||||||
* Constraints cannot have extras (see :issue:`6628`)
|
* Constraints cannot have extras (see :issue:`6628`)
|
||||||
|
|
1
news/9056.doc.rst
Normal file
1
news/9056.doc.rst
Normal file
|
@ -0,0 +1 @@
|
||||||
|
Improve migration guide to reflect changes in new resolver behavior.
|
Loading…
Reference in a new issue