2014-02-12 06:55:43 +01:00
|
|
|
|
==========
|
|
|
|
|
User Guide
|
|
|
|
|
==========
|
|
|
|
|
|
2017-11-12 17:04:37 +01:00
|
|
|
|
.. contents::
|
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2017-09-28 23:15:51 +02:00
|
|
|
|
Running pip
|
2020-02-11 14:00:03 +01:00
|
|
|
|
===========
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
|
|
|
|
pip is a command line program. When you install pip, a ``pip`` command is added
|
2020-07-29 13:07:32 +02:00
|
|
|
|
to your system, which can be run from the command prompt as follows:
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip <pip arguments>
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
``python -m pip`` executes pip using the Python interpreter you
|
|
|
|
|
specified as python. So ``/usr/bin/python3.7 -m pip`` means
|
|
|
|
|
you are executing pip for your interpreter located at /usr/bin/python3.7.
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip <pip arguments>
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
``py -m pip`` executes pip using the latest Python interpreter you
|
|
|
|
|
have installed. For more details, read the `Python Windows launcher`_ docs.
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
|
|
|
|
|
2014-02-12 06:55:43 +01:00
|
|
|
|
Installing Packages
|
2020-02-11 14:00:03 +01:00
|
|
|
|
===================
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
pip supports installing from `PyPI`_, version control, local projects, and
|
|
|
|
|
directly from distribution files.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The most common scenario is to install from `PyPI`_ using :ref:`Requirement
|
2020-07-29 13:07:32 +02:00
|
|
|
|
Specifiers`
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install SomePackage # latest version
|
|
|
|
|
python -m pip install SomePackage==1.0.4 # specific version
|
|
|
|
|
python -m pip install 'SomePackage>=1.0.4' # minimum version
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install SomePackage # latest version
|
|
|
|
|
py -m pip install SomePackage==1.0.4 # specific version
|
|
|
|
|
py -m pip install 'SomePackage>=1.0.4' # minimum version
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
For more information and examples, see the :ref:`pip install` reference.
|
|
|
|
|
|
2018-04-13 14:08:51 +02:00
|
|
|
|
.. _PyPI: https://pypi.org/
|
2015-10-07 22:35:27 +02:00
|
|
|
|
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2019-10-14 13:51:24 +02:00
|
|
|
|
Basic Authentication Credentials
|
2020-02-11 14:00:03 +01:00
|
|
|
|
================================
|
2019-10-14 13:51:24 +02:00
|
|
|
|
|
2020-01-28 01:38:22 +01:00
|
|
|
|
pip supports basic authentication credentials. Basically, in the URL there is
|
2019-10-14 13:51:24 +02:00
|
|
|
|
a username and password separated by ``:``.
|
|
|
|
|
|
2019-11-09 11:04:58 +01:00
|
|
|
|
``https://[username[:password]@]pypi.company.com/simple``
|
2019-10-25 13:10:05 +02:00
|
|
|
|
|
|
|
|
|
Certain special characters are not valid in the authentication part of URLs.
|
2019-11-13 03:05:42 +01:00
|
|
|
|
If the user or password part of your login credentials contain any of the
|
|
|
|
|
special characters
|
|
|
|
|
`here <https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters>`_
|
|
|
|
|
then they must be percent-encoded. For example, for a
|
2019-10-25 13:10:05 +02:00
|
|
|
|
user with username "user" and password "he//o" accessing a repository at
|
|
|
|
|
pypi.company.com, the index URL with credentials would look like:
|
|
|
|
|
|
|
|
|
|
``https://user:he%2F%2Fo@pypi.company.com``
|
|
|
|
|
|
2019-11-09 11:04:58 +01:00
|
|
|
|
Support for percent-encoded authentication in index URLs was added in pip 10.0.0
|
2019-11-12 14:00:51 +01:00
|
|
|
|
(in `#3236 <https://github.com/pypa/pip/issues/3236>`_). Users that must use authentication
|
2019-11-09 11:04:58 +01:00
|
|
|
|
for their Python repository on systems with older pip versions should make the latest
|
|
|
|
|
get-pip.py available in their environment to bootstrap pip to a recent-enough version.
|
|
|
|
|
|
2019-10-25 13:10:05 +02:00
|
|
|
|
For indexes that only require single-part authentication tokens, provide the token
|
|
|
|
|
as the "username" and do not provide a password, for example -
|
2019-10-19 18:36:11 +02:00
|
|
|
|
|
2019-10-25 13:10:05 +02:00
|
|
|
|
``https://0123456789abcdef@pypi.company.com``
|
2019-10-19 18:36:11 +02:00
|
|
|
|
|
2019-10-14 13:51:24 +02:00
|
|
|
|
|
2020-08-31 17:27:34 +02:00
|
|
|
|
netrc Support
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
If no credentials are part of the URL, pip will attempt to get authentication credentials
|
|
|
|
|
for the URL’s hostname from the user’s .netrc file. This behaviour comes from the underlying
|
|
|
|
|
use of `requests`_ which in turn delegates it to the `Python standard library`_.
|
|
|
|
|
|
|
|
|
|
The .netrc file contains login and initialization information used by the auto-login process.
|
|
|
|
|
It resides in the user's home directory. The .netrc file format is simple. You specify lines
|
|
|
|
|
with a machine name and follow that with lines for the login and password that are
|
|
|
|
|
associated with that machine. Machine name is the hostname in your URL.
|
|
|
|
|
|
|
|
|
|
An example .netrc for the host example.com with a user named 'daniel', using the password
|
|
|
|
|
'qwerty' would look like:
|
|
|
|
|
|
|
|
|
|
.. code-block:: shell
|
|
|
|
|
|
|
|
|
|
machine example.com
|
|
|
|
|
login daniel
|
|
|
|
|
password qwerty
|
|
|
|
|
|
|
|
|
|
As mentioned in the `standard library docs <https://docs.python.org/3/library/netrc.html>`_,
|
2020-08-31 17:43:26 +02:00
|
|
|
|
only ASCII characters are allowed. Whitespace and non-printable characters are not allowed in passwords.
|
2020-08-31 17:27:34 +02:00
|
|
|
|
|
|
|
|
|
|
2020-07-27 12:59:31 +02:00
|
|
|
|
Keyring Support
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
pip also supports credentials stored in your keyring using the `keyring`_
|
2020-07-28 02:42:01 +02:00
|
|
|
|
library. Note that ``keyring`` will need to be installed separately, as pip
|
|
|
|
|
does not come with it included.
|
2020-07-27 12:59:31 +02:00
|
|
|
|
|
|
|
|
|
.. code-block:: shell
|
|
|
|
|
|
|
|
|
|
pip install keyring
|
|
|
|
|
echo your-password | keyring set pypi.company.com your-username
|
|
|
|
|
pip install your-package --extra-index-url https://pypi.company.com/
|
|
|
|
|
|
|
|
|
|
.. _keyring: https://pypi.org/project/keyring/
|
|
|
|
|
|
|
|
|
|
|
2018-07-06 06:34:12 +02:00
|
|
|
|
Using a Proxy Server
|
2020-02-11 14:00:03 +01:00
|
|
|
|
====================
|
2018-07-06 06:34:12 +02:00
|
|
|
|
|
|
|
|
|
When installing packages from `PyPI`_, pip requires internet access, which
|
|
|
|
|
in many corporate environments requires an outbound HTTP proxy server.
|
|
|
|
|
|
|
|
|
|
pip can be configured to connect through a proxy server in various ways:
|
|
|
|
|
|
|
|
|
|
* using the ``--proxy`` command-line option to specify a proxy in the form
|
|
|
|
|
``[user:passwd@]proxy.server:port``
|
|
|
|
|
* using ``proxy`` in a :ref:`config-file`
|
|
|
|
|
* by setting the standard environment-variables ``http_proxy``, ``https_proxy``
|
|
|
|
|
and ``no_proxy``.
|
2019-03-31 11:37:02 +02:00
|
|
|
|
* using the environment variable ``PIP_USER_AGENT_USER_DATA`` to include
|
|
|
|
|
a JSON-encoded string in the user-agent variable used in pip's requests.
|
2018-07-06 06:34:12 +02:00
|
|
|
|
|
2018-07-22 20:13:34 +02:00
|
|
|
|
|
|
|
|
|
.. _`Requirements Files`:
|
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2014-02-12 06:55:43 +01:00
|
|
|
|
Requirements Files
|
2020-02-11 14:00:03 +01:00
|
|
|
|
==================
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
"Requirements files" are files containing a list of items to be
|
2020-07-29 13:07:32 +02:00
|
|
|
|
installed using :ref:`pip install` like so:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install -r requirements.txt
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install -r requirements.txt
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
Details on the format of the files are here: :ref:`Requirements File Format`.
|
|
|
|
|
|
|
|
|
|
Logically, a Requirements file is just a list of :ref:`pip install` arguments
|
2016-02-11 20:10:13 +01:00
|
|
|
|
placed in a file. Note that you should not rely on the items in the file being
|
|
|
|
|
installed by pip in any particular order.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
In practice, there are 4 common uses of Requirements files:
|
|
|
|
|
|
|
|
|
|
1. Requirements files are used to hold the result from :ref:`pip freeze` for the
|
|
|
|
|
purpose of achieving :ref:`repeatable installations <Repeatability>`. In
|
|
|
|
|
this case, your requirement file contains a pinned version of everything that
|
2019-09-24 14:01:33 +02:00
|
|
|
|
was installed when ``pip freeze`` was run.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
|
|
|
|
.. code-block:: shell
|
|
|
|
|
|
2020-08-16 20:07:09 +02:00
|
|
|
|
python -m pip freeze > requirements.txt
|
|
|
|
|
python -m pip install -r requirements.txt
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-07-30 09:03:16 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-08-16 20:07:09 +02:00
|
|
|
|
py -m pip freeze > requirements.txt
|
|
|
|
|
py -m pip install -r requirements.txt
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
2. Requirements files are used to force pip to properly resolve dependencies.
|
|
|
|
|
As it is now, pip `doesn't have true dependency resolution
|
|
|
|
|
<https://github.com/pypa/pip/issues/988>`_, but instead simply uses the first
|
2019-09-24 14:07:54 +02:00
|
|
|
|
specification it finds for a project. E.g. if ``pkg1`` requires
|
|
|
|
|
``pkg3>=1.0`` and ``pkg2`` requires ``pkg3>=1.0,<=2.0``, and if ``pkg1`` is
|
|
|
|
|
resolved first, pip will only use ``pkg3>=1.0``, and could easily end up
|
|
|
|
|
installing a version of ``pkg3`` that conflicts with the needs of ``pkg2``.
|
|
|
|
|
To solve this problem, you can place ``pkg3>=1.0,<=2.0`` (i.e. the correct
|
|
|
|
|
specification) into your requirements file directly along with the other top
|
|
|
|
|
level requirements. Like so::
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
pkg1
|
|
|
|
|
pkg2
|
|
|
|
|
pkg3>=1.0,<=2.0
|
|
|
|
|
|
|
|
|
|
3. Requirements files are used to force pip to install an alternate version of a
|
2019-09-24 14:01:33 +02:00
|
|
|
|
sub-dependency. For example, suppose ``ProjectA`` in your requirements file
|
|
|
|
|
requires ``ProjectB``, but the latest version (v1.3) has a bug, you can force
|
2019-09-24 14:07:54 +02:00
|
|
|
|
pip to accept earlier versions like so::
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
ProjectA
|
|
|
|
|
ProjectB<1.3
|
|
|
|
|
|
|
|
|
|
4. Requirements files are used to override a dependency with a local patch that
|
2019-09-24 14:07:54 +02:00
|
|
|
|
lives in version control. For example, suppose a dependency
|
|
|
|
|
``SomeDependency`` from PyPI has a bug, and you can't wait for an upstream
|
|
|
|
|
fix.
|
2016-02-07 00:11:45 +01:00
|
|
|
|
You could clone/copy the src, make the fix, and place it in VCS with the tag
|
2019-09-24 14:07:54 +02:00
|
|
|
|
``sometag``. You'd reference it in your requirements file with a line like
|
|
|
|
|
so::
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
git+https://myvcs.com/some_dependency@sometag#egg=SomeDependency
|
|
|
|
|
|
2019-09-24 14:01:33 +02:00
|
|
|
|
If ``SomeDependency`` was previously a top-level requirement in your
|
2014-02-12 06:55:43 +01:00
|
|
|
|
requirements file, then **replace** that line with the new line. If
|
2019-09-24 14:01:33 +02:00
|
|
|
|
``SomeDependency`` is a sub-dependency, then **add** the new line.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It's important to be clear that pip determines package dependencies using
|
|
|
|
|
`install_requires metadata
|
2016-06-06 01:28:35 +02:00
|
|
|
|
<https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-dependencies>`_,
|
2019-09-24 14:01:33 +02:00
|
|
|
|
not by discovering ``requirements.txt`` files embedded in projects.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
See also:
|
|
|
|
|
|
|
|
|
|
* :ref:`Requirements File Format`
|
|
|
|
|
* :ref:`pip freeze`
|
|
|
|
|
* `"setup.py vs requirements.txt" (an article by Donald Stufft)
|
2015-09-30 18:32:24 +02:00
|
|
|
|
<https://caremad.io/2013/07/setup-vs-requirement/>`_
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
2015-06-02 05:39:10 +02:00
|
|
|
|
.. _`Constraints Files`:
|
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2015-06-02 05:39:10 +02:00
|
|
|
|
Constraints Files
|
2020-02-11 14:00:03 +01:00
|
|
|
|
=================
|
2015-06-02 05:39:10 +02:00
|
|
|
|
|
|
|
|
|
Constraints files are requirements files that only control which version of a
|
|
|
|
|
requirement is installed, not whether it is installed or not. Their syntax and
|
|
|
|
|
contents is nearly identical to :ref:`Requirements Files`. There is one key
|
|
|
|
|
difference: Including a package in a constraints file does not trigger
|
|
|
|
|
installation of the package.
|
|
|
|
|
|
2020-07-29 13:07:32 +02:00
|
|
|
|
Use a constraints file like so:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install -c constraints.txt
|
2015-06-02 05:39:10 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2015-06-02 05:39:10 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install -c constraints.txt
|
2015-06-02 05:39:10 +02:00
|
|
|
|
|
|
|
|
|
Constraints files are used for exactly the same reason as requirements files
|
|
|
|
|
when you don't know exactly what things you want to install. For instance, say
|
|
|
|
|
that the "helloworld" package doesn't work in your environment, so you have a
|
|
|
|
|
local patched version. Some things you install depend on "helloworld", and some
|
|
|
|
|
don't.
|
|
|
|
|
|
|
|
|
|
One way to ensure that the patched version is used consistently is to
|
|
|
|
|
manually audit the dependencies of everything you install, and if "helloworld"
|
|
|
|
|
is present, write a requirements file to use when installing that thing.
|
|
|
|
|
|
|
|
|
|
Constraints files offer a better way: write a single constraints file for your
|
|
|
|
|
organisation and use that everywhere. If the thing being installed requires
|
|
|
|
|
"helloworld" to be installed, your fixed version specified in your constraints
|
|
|
|
|
file will be used.
|
|
|
|
|
|
|
|
|
|
Constraints file support was added in pip 7.1.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
.. _`Installing from Wheels`:
|
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2014-02-12 06:55:43 +01:00
|
|
|
|
Installing from Wheels
|
2020-02-11 14:00:03 +01:00
|
|
|
|
======================
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
"Wheel" is a built, archive format that can greatly speed installation compared
|
|
|
|
|
to building and installing from source archives. For more information, see the
|
2018-06-25 12:43:59 +02:00
|
|
|
|
`Wheel docs <https://wheel.readthedocs.io>`_ , :pep:`427`, and :pep:`425`.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-02-11 14:51:29 +01:00
|
|
|
|
pip prefers Wheels where they are available. To disable this, use the
|
2015-04-17 05:03:34 +02:00
|
|
|
|
:ref:`--no-binary <install_--no-binary>` flag for :ref:`pip install`.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
If no satisfactory wheels are found, pip will default to finding source
|
|
|
|
|
archives.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
To install directly from a wheel archive:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install SomePackage-1.0-py2.py3-none-any.whl
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install SomePackage-1.0-py2.py3-none-any.whl
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For the cases where wheels are not available, pip offers :ref:`pip wheel` as a
|
|
|
|
|
convenience, to build wheels for all your requirements and dependencies.
|
|
|
|
|
|
|
|
|
|
:ref:`pip wheel` requires the `wheel package
|
2018-04-13 14:08:51 +02:00
|
|
|
|
<https://pypi.org/project/wheel/>`_ to be installed, which provides the
|
2014-02-12 06:55:43 +01:00
|
|
|
|
"bdist_wheel" setuptools extension that it uses.
|
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
To build wheels for your requirements and all their dependencies to a local
|
|
|
|
|
directory:
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install wheel
|
|
|
|
|
python -m pip wheel --wheel-dir=/local/wheels -r requirements.txt
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install wheel
|
|
|
|
|
py -m pip wheel --wheel-dir=/local/wheels -r requirements.txt
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
And *then* to install those requirements just using your local directory of
|
|
|
|
|
wheels (and not from PyPI):
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install --no-index --find-links=/local/wheels -r requirements.txt
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install --no-index --find-links=/local/wheels -r requirements.txt
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Uninstalling Packages
|
2020-02-11 14:00:03 +01:00
|
|
|
|
=====================
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
pip is able to uninstall most packages like so:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip uninstall SomePackage
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip uninstall SomePackage
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
pip also performs an automatic uninstall of an old version of a package
|
|
|
|
|
before upgrading to a newer version.
|
|
|
|
|
|
|
|
|
|
For more information and examples, see the :ref:`pip uninstall` reference.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Listing Packages
|
2020-02-11 14:00:03 +01:00
|
|
|
|
================
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
To list installed packages:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
$ python -m pip list
|
|
|
|
|
docutils (0.9.1)
|
|
|
|
|
Jinja2 (2.6)
|
|
|
|
|
Pygments (1.5)
|
|
|
|
|
Sphinx (1.1.2)
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
C:\> py -m pip list
|
|
|
|
|
docutils (0.9.1)
|
|
|
|
|
Jinja2 (2.6)
|
|
|
|
|
Pygments (1.5)
|
|
|
|
|
Sphinx (1.1.2)
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
To list outdated packages, and show the latest version available:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
$ python -m pip list --outdated
|
|
|
|
|
docutils (Current: 0.9.1 Latest: 0.10)
|
|
|
|
|
Sphinx (Current: 1.1.2 Latest: 1.1.3)
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
C:\> py -m pip list --outdated
|
|
|
|
|
docutils (Current: 0.9.1 Latest: 0.10)
|
|
|
|
|
Sphinx (Current: 1.1.2 Latest: 1.1.3)
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
To show details about an installed package:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
$ python -m pip show sphinx
|
|
|
|
|
---
|
|
|
|
|
Name: Sphinx
|
|
|
|
|
Version: 1.1.3
|
|
|
|
|
Location: /my/env/lib/pythonx.x/site-packages
|
|
|
|
|
Requires: Pygments, Jinja2, docutils
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
C:\> py -m pip show sphinx
|
|
|
|
|
---
|
|
|
|
|
Name: Sphinx
|
|
|
|
|
Version: 1.1.3
|
|
|
|
|
Location: /my/env/lib/pythonx.x/site-packages
|
|
|
|
|
Requires: Pygments, Jinja2, docutils
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
For more information and examples, see the :ref:`pip list` and :ref:`pip show`
|
|
|
|
|
reference pages.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Searching for Packages
|
2020-02-11 14:00:03 +01:00
|
|
|
|
======================
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
pip can search `PyPI`_ for packages using the ``pip search``
|
2020-07-29 13:07:32 +02:00
|
|
|
|
command:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip search "query"
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip search "query"
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
The query will be used to search the names and summaries of all
|
|
|
|
|
packages.
|
|
|
|
|
|
|
|
|
|
For more information and examples, see the :ref:`pip search` reference.
|
|
|
|
|
|
|
|
|
|
.. _`Configuration`:
|
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2014-02-12 06:55:43 +01:00
|
|
|
|
Configuration
|
2020-02-11 14:00:03 +01:00
|
|
|
|
=============
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
.. _config-file:
|
|
|
|
|
|
|
|
|
|
Config file
|
2020-02-11 14:00:03 +01:00
|
|
|
|
-----------
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
pip allows you to set all command line option defaults in a standard ini
|
|
|
|
|
style config file.
|
|
|
|
|
|
|
|
|
|
The names and locations of the configuration files vary slightly across
|
2020-07-25 14:56:53 +02:00
|
|
|
|
platforms. You may have per-user, per-virtualenv or global (shared amongst
|
2014-08-15 09:23:46 +02:00
|
|
|
|
all users) configuration:
|
|
|
|
|
|
|
|
|
|
**Per-user**:
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2014-09-10 17:15:09 +02:00
|
|
|
|
* On Unix the default configuration file is: :file:`$HOME/.config/pip/pip.conf`
|
|
|
|
|
which respects the ``XDG_CONFIG_HOME`` environment variable.
|
2016-11-06 18:24:43 +01:00
|
|
|
|
* On macOS the configuration file is
|
2016-11-19 15:01:38 +01:00
|
|
|
|
:file:`$HOME/Library/Application Support/pip/pip.conf`
|
|
|
|
|
if directory ``$HOME/Library/Application Support/pip`` exists
|
|
|
|
|
else :file:`$HOME/.config/pip/pip.conf`.
|
2014-09-10 17:15:09 +02:00
|
|
|
|
* On Windows the configuration file is :file:`%APPDATA%\\pip\\pip.ini`.
|
|
|
|
|
|
|
|
|
|
There are also a legacy per-user configuration file which is also respected,
|
|
|
|
|
these are located at:
|
|
|
|
|
|
2016-11-06 18:24:43 +01:00
|
|
|
|
* On Unix and macOS the configuration file is: :file:`$HOME/.pip/pip.conf`
|
2014-08-15 09:23:46 +02:00
|
|
|
|
* On Windows the configuration file is: :file:`%HOME%\\pip\\pip.ini`
|
|
|
|
|
|
|
|
|
|
You can set a custom path location for this config file using the environment
|
|
|
|
|
variable ``PIP_CONFIG_FILE``.
|
|
|
|
|
|
|
|
|
|
**Inside a virtualenv**:
|
|
|
|
|
|
2016-11-06 18:24:43 +01:00
|
|
|
|
* On Unix and macOS the file is :file:`$VIRTUAL_ENV/pip.conf`
|
2014-08-15 09:23:46 +02:00
|
|
|
|
* On Windows the file is: :file:`%VIRTUAL_ENV%\\pip.ini`
|
|
|
|
|
|
2020-07-25 14:56:53 +02:00
|
|
|
|
**Global**:
|
2014-08-15 09:23:46 +02:00
|
|
|
|
|
2015-05-10 01:39:55 +02:00
|
|
|
|
* On Unix the file may be located in :file:`/etc/pip.conf`. Alternatively
|
2014-08-15 09:23:46 +02:00
|
|
|
|
it may be in a "pip" subdirectory of any of the paths set in the
|
|
|
|
|
environment variable ``XDG_CONFIG_DIRS`` (if it exists), for example
|
|
|
|
|
:file:`/etc/xdg/pip/pip.conf`.
|
2016-11-06 18:24:43 +01:00
|
|
|
|
* On macOS the file is: :file:`/Library/Application Support/pip/pip.conf`
|
2014-08-15 09:23:46 +02:00
|
|
|
|
* On Windows XP the file is:
|
2015-03-16 21:30:13 +01:00
|
|
|
|
:file:`C:\\Documents and Settings\\All Users\\Application Data\\pip\\pip.ini`
|
2014-08-15 09:23:46 +02:00
|
|
|
|
* On Windows 7 and later the file is hidden, but writeable at
|
2015-03-16 21:30:13 +01:00
|
|
|
|
:file:`C:\\ProgramData\\pip\\pip.ini`
|
2020-07-25 19:03:31 +02:00
|
|
|
|
* Global configuration is not supported on Windows Vista.
|
|
|
|
|
|
2020-07-25 23:15:01 +02:00
|
|
|
|
The global configuration file is shared by all Python installations.
|
2014-08-15 09:23:46 +02:00
|
|
|
|
|
|
|
|
|
If multiple configuration files are found by pip then they are combined in
|
|
|
|
|
the following order:
|
|
|
|
|
|
2020-07-25 19:03:31 +02:00
|
|
|
|
1. The global file is read
|
2018-07-07 06:33:14 +02:00
|
|
|
|
2. The per-user file is read
|
|
|
|
|
3. The virtualenv-specific file is read
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2014-08-15 09:23:46 +02:00
|
|
|
|
Each file read overrides any values read from previous files, so if the
|
2020-07-25 19:03:31 +02:00
|
|
|
|
global timeout is specified in both the global file and the per-user file
|
2018-07-07 06:33:14 +02:00
|
|
|
|
then the latter value will be used.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
The names of the settings are derived from the long command line option, e.g.
|
|
|
|
|
if you want to use a different package index (``--index-url``) and set the
|
|
|
|
|
HTTP timeout (``--default-timeout``) to 60 seconds your config file would
|
|
|
|
|
look like this:
|
|
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
|
|
[global]
|
|
|
|
|
timeout = 60
|
2018-06-10 17:35:00 +02:00
|
|
|
|
index-url = https://download.zope.org/ppix
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
Each subcommand can be configured optionally in its own section so that every
|
|
|
|
|
global setting with the same name will be overridden; e.g. decreasing the
|
2019-09-24 14:01:33 +02:00
|
|
|
|
``timeout`` to ``10`` seconds when running the ``freeze``
|
2019-12-10 23:18:38 +01:00
|
|
|
|
(:ref:`pip freeze`) command and using
|
2014-02-12 06:55:43 +01:00
|
|
|
|
``60`` seconds for all other commands is possible with:
|
|
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
|
|
[global]
|
|
|
|
|
timeout = 60
|
|
|
|
|
|
|
|
|
|
[freeze]
|
|
|
|
|
timeout = 10
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Boolean options like ``--ignore-installed`` or ``--no-dependencies`` can be
|
|
|
|
|
set like this:
|
|
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
|
|
[install]
|
|
|
|
|
ignore-installed = true
|
|
|
|
|
no-dependencies = yes
|
|
|
|
|
|
2019-04-01 04:56:13 +02:00
|
|
|
|
To enable the boolean options ``--no-compile``, ``--no-warn-script-location``
|
|
|
|
|
and ``--no-cache-dir``, falsy values have to be used:
|
2015-05-18 10:32:02 +02:00
|
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
|
|
[global]
|
|
|
|
|
no-cache-dir = false
|
|
|
|
|
|
|
|
|
|
[install]
|
|
|
|
|
no-compile = no
|
2019-04-01 04:56:13 +02:00
|
|
|
|
no-warn-script-location = false
|
2015-05-18 10:32:02 +02:00
|
|
|
|
|
2020-07-15 10:26:04 +02:00
|
|
|
|
For options which can be repeated like ``--verbose`` and ``--quiet``,
|
|
|
|
|
a non-negative integer can be used to represent the level to be specified:
|
|
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
|
|
[global]
|
|
|
|
|
quiet = 0
|
|
|
|
|
verbose = 2
|
|
|
|
|
|
2020-03-28 13:01:13 +01:00
|
|
|
|
It is possible to append values to a section within a configuration file such as the pip.ini file.
|
|
|
|
|
This is applicable to appending options like ``--find-links`` or ``--trusted-host``,
|
|
|
|
|
which can be written on multiple lines:
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
|
|
[global]
|
|
|
|
|
find-links =
|
|
|
|
|
http://download.example.com
|
|
|
|
|
|
|
|
|
|
[install]
|
|
|
|
|
find-links =
|
|
|
|
|
http://mirror1.example.com
|
|
|
|
|
http://mirror2.example.com
|
|
|
|
|
|
2020-03-28 13:01:13 +01:00
|
|
|
|
trusted-host =
|
|
|
|
|
http://mirror1.example.com
|
|
|
|
|
http://mirror2.example.com
|
|
|
|
|
|
|
|
|
|
This enables users to add additional values in the order of entry for such command line arguments.
|
|
|
|
|
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
Environment Variables
|
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
pip's command line options can be set with environment variables using the
|
|
|
|
|
format ``PIP_<UPPER_LONG_NAME>`` . Dashes (``-``) have to be replaced with
|
|
|
|
|
underscores (``_``).
|
|
|
|
|
|
2020-07-29 13:07:32 +02:00
|
|
|
|
For example, to set the default timeout:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
export PIP_DEFAULT_TIMEOUT=60
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
set PIP_DEFAULT_TIMEOUT=60
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
|
|
|
|
This is the same as passing the option to pip directly:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip --default-timeout=60 [...]
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip --default-timeout=60 [...]
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2017-09-29 23:49:22 +02:00
|
|
|
|
For command line options which can be repeated, use a space to separate
|
2020-07-29 13:07:32 +02:00
|
|
|
|
multiple values. For example:
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
set PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
|
|
|
|
is the same as calling:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-07-15 10:26:04 +02:00
|
|
|
|
Options that do not take a value, but can be repeated (such as ``--verbose``)
|
|
|
|
|
can be specified using the number of repetitions, so::
|
|
|
|
|
|
|
|
|
|
export PIP_VERBOSE=3
|
|
|
|
|
|
|
|
|
|
is the same as calling::
|
|
|
|
|
|
|
|
|
|
pip install -vvv
|
|
|
|
|
|
2018-11-24 15:00:41 +01:00
|
|
|
|
.. note::
|
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
Environment variables set to be empty string will not be treated as false.
|
|
|
|
|
Please use ``no``, ``false`` or ``0`` instead.
|
2018-11-24 15:00:41 +01:00
|
|
|
|
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-03-24 11:13:34 +01:00
|
|
|
|
.. _config-precedence:
|
|
|
|
|
|
2014-02-12 06:55:43 +01:00
|
|
|
|
Config Precedence
|
|
|
|
|
-----------------
|
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
Command line options have precedence over environment variables, which have
|
|
|
|
|
precedence over the config file.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
Within the config file, command specific sections have precedence over the
|
|
|
|
|
global section.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
|
|
- ``--host=foo`` overrides ``PIP_HOST=foo``
|
|
|
|
|
- ``PIP_HOST=foo`` overrides a config file with ``[global] host = foo``
|
|
|
|
|
- A command specific section in the config file ``[<command>] host = bar``
|
|
|
|
|
overrides the option with same name in the ``[global]`` config file section
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Command Completion
|
2020-02-11 14:00:03 +01:00
|
|
|
|
==================
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2016-07-21 01:57:20 +02:00
|
|
|
|
pip comes with support for command line completion in bash, zsh and fish.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
To setup for bash::
|
|
|
|
|
|
2020-08-16 20:07:09 +02:00
|
|
|
|
python -m pip completion --bash >> ~/.profile
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
To setup for zsh::
|
|
|
|
|
|
2020-08-16 20:07:09 +02:00
|
|
|
|
python -m pip completion --zsh >> ~/.zprofile
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2016-07-21 01:57:20 +02:00
|
|
|
|
To setup for fish::
|
|
|
|
|
|
2020-08-16 20:07:09 +02:00
|
|
|
|
python -m pip completion --fish > ~/.config/fish/completions/pip.fish
|
2016-07-21 01:57:20 +02:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
Alternatively, you can use the result of the ``completion`` command directly
|
|
|
|
|
with the eval function of your shell, e.g. by adding the following to your
|
|
|
|
|
startup file::
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
eval "`pip completion --bash`"
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2015-09-11 06:30:38 +02:00
|
|
|
|
.. _`Installing from local packages`:
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2015-09-11 06:30:38 +02:00
|
|
|
|
Installing from local packages
|
2020-02-11 14:00:03 +01:00
|
|
|
|
==============================
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2015-09-11 06:30:38 +02:00
|
|
|
|
In some cases, you may want to install from local packages only, with no traffic
|
|
|
|
|
to PyPI.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-07-29 13:07:32 +02:00
|
|
|
|
First, download the archives that fulfill your requirements:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip download --destination-directory DIR -r requirements.txt
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2015-09-11 06:30:38 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip download --destination-directory DIR -r requirements.txt
|
2015-09-11 06:30:38 +02:00
|
|
|
|
|
2018-11-01 18:58:48 +01:00
|
|
|
|
Note that ``pip download`` will look in your wheel cache first, before
|
2015-09-11 06:30:38 +02:00
|
|
|
|
trying to download from PyPI. If you've never installed your requirements
|
|
|
|
|
before, you won't have a wheel cache for those items. In that case, if some of
|
|
|
|
|
your requirements don't come as wheels from PyPI, and you want wheels, then run
|
2020-07-29 13:07:32 +02:00
|
|
|
|
this instead:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip wheel --wheel-dir DIR -r requirements.txt
|
2015-09-11 06:30:38 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2015-09-11 06:30:38 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2015-09-11 06:30:38 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip wheel --wheel-dir DIR -r requirements.txt
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2015-09-11 06:30:38 +02:00
|
|
|
|
Then, to install from local only, you'll be using :ref:`--find-links
|
2020-07-29 13:07:32 +02:00
|
|
|
|
<install_--find-links>` and :ref:`--no-index <install_--no-index>` like so:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install --no-index --find-links=DIR -r requirements.txt
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install --no-index --find-links=DIR -r requirements.txt
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
2014-08-24 19:48:36 +02:00
|
|
|
|
"Only if needed" Recursive Upgrade
|
2020-02-11 14:00:03 +01:00
|
|
|
|
==================================
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2017-01-14 17:26:50 +01:00
|
|
|
|
``pip install --upgrade`` now has a ``--upgrade-strategy`` option which
|
|
|
|
|
controls how pip handles upgrading of dependencies. There are 2 upgrade
|
|
|
|
|
strategies supported:
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2017-01-14 17:26:50 +01:00
|
|
|
|
- ``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
|
2017-05-19 13:39:48 +02:00
|
|
|
|
|
|
|
|
|
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.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2017-01-14 17:26:50 +01:00
|
|
|
|
As an historic note, an earlier "fix" for getting the ``only-if-needed``
|
2020-07-29 13:07:32 +02:00
|
|
|
|
behaviour was:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install --upgrade --no-deps SomePackage
|
|
|
|
|
python -m pip install SomePackage
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install --upgrade --no-deps SomePackage
|
|
|
|
|
py -m pip install SomePackage
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
2017-01-14 17:26:50 +01:00
|
|
|
|
A proposal for an ``upgrade-all`` command is being considered as a safer
|
|
|
|
|
alternative to the behaviour of eager upgrading.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
User Installs
|
2020-02-11 14:00:03 +01:00
|
|
|
|
=============
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
With Python 2.6 came the `"user scheme" for installation
|
2018-06-10 17:35:00 +02:00
|
|
|
|
<https://docs.python.org/3/install/index.html#alternate-installation-the-user-scheme>`_,
|
2014-02-12 06:55:43 +01:00
|
|
|
|
which means that all Python distributions support an alternative install
|
|
|
|
|
location that is specific to a user. The default location for each OS is
|
|
|
|
|
explained in the python documentation for the `site.USER_BASE
|
2019-09-24 14:07:54 +02:00
|
|
|
|
<https://docs.python.org/3/library/site.html#site.USER_BASE>`_ variable.
|
|
|
|
|
This mode of installation can be turned on by specifying the :ref:`--user
|
2014-02-12 06:55:43 +01:00
|
|
|
|
<install_--user>` option to ``pip install``.
|
|
|
|
|
|
|
|
|
|
Moreover, the "user scheme" can be customized by setting the
|
2019-09-24 14:07:54 +02:00
|
|
|
|
``PYTHONUSERBASE`` environment variable, which updates the value of
|
|
|
|
|
``site.USER_BASE``.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
To install "SomePackage" into an environment with site.USER_BASE customized to
|
2020-07-29 13:07:32 +02:00
|
|
|
|
'/myappenv', do the following:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
export PYTHONUSERBASE=/myappenv
|
|
|
|
|
python -m pip install --user SomePackage
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
set PYTHONUSERBASE=c:/myappenv
|
|
|
|
|
py -m pip install --user SomePackage
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
``pip install --user`` follows four rules:
|
|
|
|
|
|
|
|
|
|
#. When globally installed packages are on the python path, and they *conflict*
|
|
|
|
|
with the installation requirements, they are ignored, and *not*
|
|
|
|
|
uninstalled.
|
|
|
|
|
#. When globally installed packages are on the python path, and they *satisfy*
|
|
|
|
|
the installation requirements, pip does nothing, and reports that
|
|
|
|
|
requirement is satisfied (similar to how global packages can satisfy
|
|
|
|
|
requirements when installing packages in a ``--system-site-packages``
|
|
|
|
|
virtualenv).
|
|
|
|
|
#. pip will not perform a ``--user`` install in a ``--no-site-packages``
|
|
|
|
|
virtualenv (i.e. the default kind of virtualenv), due to the user site not
|
|
|
|
|
being on the python path. The installation would be pointless.
|
|
|
|
|
#. In a ``--system-site-packages`` virtualenv, pip will not install a package
|
|
|
|
|
that conflicts with a package in the virtualenv site-packages. The --user
|
|
|
|
|
installation would lack sys.path precedence and be pointless.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
To make the rules clearer, here are some examples:
|
|
|
|
|
|
2020-07-29 13:07:32 +02:00
|
|
|
|
From within a ``--no-site-packages`` virtualenv (i.e. the default kind):
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
$ python -m pip install --user SomePackage
|
|
|
|
|
Can not perform a '--user' install. User site-packages are not visible in this virtualenv.
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
C:\> py -m pip install --user SomePackage
|
|
|
|
|
Can not perform a '--user' install. User site-packages are not visible in this virtualenv.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3``
|
2020-07-29 13:07:32 +02:00
|
|
|
|
is already installed in the virtualenv:
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
$ python -m pip install --user SomePackage==0.4
|
|
|
|
|
Will not install to the user site because it will lack sys.path precedence
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
C:\> py -m pip install --user SomePackage==0.4
|
|
|
|
|
Will not install to the user site because it will lack sys.path precedence
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-07-29 13:07:32 +02:00
|
|
|
|
From within a real python, where ``SomePackage`` is *not* installed globally:
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
$ python -m pip install --user SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Successfully installed SomePackage
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
C:\> py -m pip install --user SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Successfully installed SomePackage
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
From within a real python, where ``SomePackage`` *is* installed globally, but
|
2020-07-29 13:07:32 +02:00
|
|
|
|
is *not* the latest version:
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
$ python -m pip install --user SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Requirement already satisfied (use --upgrade to upgrade)
|
|
|
|
|
$ python -m pip install --user --upgrade SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Successfully installed SomePackage
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
C:\> py -m pip install --user SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Requirement already satisfied (use --upgrade to upgrade)
|
|
|
|
|
C:\> py -m pip install --user --upgrade SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Successfully installed SomePackage
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
From within a real python, where ``SomePackage`` *is* installed globally, and
|
2020-07-29 13:07:32 +02:00
|
|
|
|
is the latest version:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
$ python -m pip install --user SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Requirement already satisfied (use --upgrade to upgrade)
|
|
|
|
|
$ python -m pip install --user --upgrade SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Requirement already up-to-date: SomePackage
|
|
|
|
|
# force the install
|
|
|
|
|
$ python -m pip install --user --ignore-installed SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Successfully installed SomePackage
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: console
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
C:\> py -m pip install --user SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Requirement already satisfied (use --upgrade to upgrade)
|
|
|
|
|
C:\> py -m pip install --user --upgrade SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Requirement already up-to-date: SomePackage
|
|
|
|
|
# force the install
|
|
|
|
|
C:\> py -m pip install --user --ignore-installed SomePackage
|
|
|
|
|
[...]
|
|
|
|
|
Successfully installed SomePackage
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
|
|
|
|
.. _`Repeatability`:
|
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2014-02-12 06:55:43 +01:00
|
|
|
|
Ensuring Repeatability
|
2020-02-11 14:00:03 +01:00
|
|
|
|
======================
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2015-10-07 22:35:27 +02:00
|
|
|
|
pip can achieve various levels of repeatability:
|
|
|
|
|
|
|
|
|
|
Pinned Version Numbers
|
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
|
|
Pinning the versions of your dependencies in the requirements file
|
|
|
|
|
protects you from bugs or incompatibilities in newly released versions::
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2015-10-07 22:35:27 +02:00
|
|
|
|
SomePackage == 1.2.3
|
|
|
|
|
DependencyOfSomePackage == 4.5.6
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2015-10-07 22:35:27 +02:00
|
|
|
|
Using :ref:`pip freeze` to generate the requirements file will ensure that not
|
|
|
|
|
only the top-level dependencies are included but their sub-dependencies as
|
|
|
|
|
well, and so on. Perform the installation using :ref:`--no-deps
|
|
|
|
|
<install_--no-deps>` for an extra dose of insurance against installing
|
|
|
|
|
anything not explicitly listed.
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2015-10-07 22:35:27 +02:00
|
|
|
|
This strategy is easy to implement and works across OSes and architectures.
|
2015-10-09 20:46:56 +02:00
|
|
|
|
However, it trusts PyPI and the certificate authority chain. It
|
|
|
|
|
also relies on indices and find-links locations not allowing
|
|
|
|
|
packages to change without a version increase. (PyPI does protect
|
|
|
|
|
against this.)
|
2015-04-23 01:00:14 +02:00
|
|
|
|
|
2015-10-07 22:35:27 +02:00
|
|
|
|
Hash-checking Mode
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
Beyond pinning version numbers, you can add hashes against which to verify
|
|
|
|
|
downloaded packages::
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2016-01-28 18:07:55 +01:00
|
|
|
|
FooProject == 1.2 --hash=sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
|
2014-02-12 06:55:43 +01:00
|
|
|
|
|
2015-10-09 20:46:56 +02:00
|
|
|
|
This protects against a compromise of PyPI or the HTTPS
|
|
|
|
|
certificate chain. It also guards against a package changing
|
|
|
|
|
without its version number changing (on indexes that allow this).
|
|
|
|
|
This approach is a good fit for automated server deployments.
|
2014-12-21 01:08:33 +01:00
|
|
|
|
|
2015-10-08 05:41:24 +02:00
|
|
|
|
Hash-checking mode is a labor-saving alternative to running a private index
|
2015-10-07 22:35:27 +02:00
|
|
|
|
server containing approved packages: it removes the need to upload packages,
|
2015-10-08 05:41:24 +02:00
|
|
|
|
maintain ACLs, and keep an audit trail (which a VCS gives you on the
|
2015-10-07 22:35:27 +02:00
|
|
|
|
requirements file for free). It can also substitute for a vendor library,
|
|
|
|
|
providing easier upgrades and less VCS noise. It does not, of course,
|
2015-10-08 05:41:24 +02:00
|
|
|
|
provide the availability benefits of a private index or a vendor library.
|
2015-10-07 22:35:27 +02:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
For more, see
|
|
|
|
|
:ref:`pip install\'s discussion of hash-checking mode <hash-checking mode>`.
|
2014-12-21 01:08:33 +01:00
|
|
|
|
|
|
|
|
|
.. _`Installation Bundle`:
|
|
|
|
|
|
2015-10-07 22:35:27 +02:00
|
|
|
|
Installation Bundles
|
|
|
|
|
--------------------
|
2014-12-21 01:08:33 +01:00
|
|
|
|
|
2015-10-11 15:15:06 +02:00
|
|
|
|
Using :ref:`pip wheel`, you can bundle up all of a project's dependencies, with
|
|
|
|
|
any compilation done, into a single archive. This allows installation when
|
|
|
|
|
index servers are unavailable and avoids time-consuming recompilation. Create
|
|
|
|
|
an archive like this::
|
2014-12-21 01:08:33 +01:00
|
|
|
|
|
|
|
|
|
$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX)
|
2020-07-29 13:07:32 +02:00
|
|
|
|
$ python -m pip wheel -r requirements.txt --wheel-dir=$tempdir
|
2014-12-21 01:08:33 +01:00
|
|
|
|
$ cwd=`pwd`
|
|
|
|
|
$ (cd "$tempdir"; tar -cjvf "$cwd/bundled.tar.bz2" *)
|
|
|
|
|
|
2015-10-11 15:15:06 +02:00
|
|
|
|
You can then install from the archive like this::
|
2014-12-21 01:08:33 +01:00
|
|
|
|
|
|
|
|
|
$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX)
|
|
|
|
|
$ (cd $tempdir; tar -xvf /path/to/bundled.tar.bz2)
|
2020-07-29 13:07:32 +02:00
|
|
|
|
$ python -m pip install --force-reinstall --ignore-installed --upgrade --no-index --no-deps $tempdir/*
|
2015-10-07 22:35:27 +02:00
|
|
|
|
|
2015-10-11 15:15:06 +02:00
|
|
|
|
Note that compiled packages are typically OS- and architecture-specific, so
|
2020-07-29 13:07:32 +02:00
|
|
|
|
these archives are not necessarily portable across macOShines.
|
2015-10-11 15:15:06 +02:00
|
|
|
|
|
|
|
|
|
Hash-checking mode can be used along with this method to ensure that future
|
|
|
|
|
archives are built with identical packages.
|
2015-10-07 22:35:27 +02:00
|
|
|
|
|
|
|
|
|
.. warning::
|
2020-02-11 14:10:42 +01:00
|
|
|
|
|
2015-10-07 22:35:27 +02:00
|
|
|
|
Finally, beware of the ``setup_requires`` keyword arg in :file:`setup.py`.
|
|
|
|
|
The (rare) packages that use it will cause those dependencies to be
|
|
|
|
|
downloaded by setuptools directly, skipping pip's protections. If you need
|
|
|
|
|
to use such a package, see :ref:`Controlling
|
|
|
|
|
setup_requires<controlling-setup-requires>`.
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2020-06-24 06:49:20 +02:00
|
|
|
|
Fixing conflicting dependencies
|
|
|
|
|
===============================
|
|
|
|
|
|
|
|
|
|
The purpose of this section of documentation is to provide practical suggestions to
|
|
|
|
|
pip users who encounter an error where pip cannot install their
|
|
|
|
|
specified packages due to conflicting dependencies (a
|
|
|
|
|
``ResolutionImpossible`` error).
|
|
|
|
|
|
|
|
|
|
This documentation is specific to the new resolver, which you can use
|
2020-07-30 19:58:47 +02:00
|
|
|
|
with the flag ``--use-feature=2020-resolver``.
|
2020-06-24 06:49:20 +02:00
|
|
|
|
|
|
|
|
|
Understanding your error message
|
|
|
|
|
--------------------------------
|
|
|
|
|
|
|
|
|
|
When you get a ``ResolutionImpossible`` error, you might see something
|
|
|
|
|
like this:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install package_coffee==0.44.1 package_tea==4.3.0
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install package_coffee==0.44.1 package_tea==4.3.0
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
|
|
|
|
::
|
2020-06-24 06:49:20 +02:00
|
|
|
|
|
2020-08-24 10:42:31 +02:00
|
|
|
|
Due to conflicting dependencies pip cannot install
|
|
|
|
|
package_coffee and package_tea:
|
|
|
|
|
- package_coffee depends on package_water<3.0.0,>=2.4.2
|
|
|
|
|
- package_tea depends on package_water==2.3.1
|
2020-06-24 06:49:20 +02:00
|
|
|
|
|
|
|
|
|
In this example, pip cannot install the packages you have requested,
|
|
|
|
|
because they each depend on different versions of the same package
|
|
|
|
|
(``package_water``):
|
|
|
|
|
|
|
|
|
|
- ``package_coffee`` version ``0.44.1`` depends on a version of
|
|
|
|
|
``package_water`` that is less than ``3.0.0`` but greater than or equal to
|
|
|
|
|
``2.4.2``
|
|
|
|
|
- ``package_tea`` version ``4.3.0`` depends on version ``2.3.1`` of
|
|
|
|
|
``package_water``
|
|
|
|
|
|
|
|
|
|
Sometimes these messages are straightforward to read, because they use
|
|
|
|
|
commonly understood comparison operators to specify the required version
|
|
|
|
|
(e.g. ``<`` or ``>``).
|
|
|
|
|
|
|
|
|
|
However, Python packaging also supports some more complex ways for
|
|
|
|
|
specifying package versions (e.g. ``~=`` or ``*``):
|
|
|
|
|
|
2020-08-24 10:48:39 +02:00
|
|
|
|
+----------+---------------------------------+--------------------------------+
|
|
|
|
|
| Operator | Description | Example |
|
|
|
|
|
+==========+=================================+================================+
|
|
|
|
|
| ``>`` | Any version greater than | ``>3.1``: any version |
|
|
|
|
|
| | the specified version. | greater than ``3.1``. |
|
|
|
|
|
+----------+---------------------------------+--------------------------------+
|
|
|
|
|
| ``<`` | Any version less than | ``<3.1``: any version |
|
|
|
|
|
| | the specified version. | less than ``3.1``. |
|
|
|
|
|
+----------+---------------------------------+--------------------------------+
|
|
|
|
|
| ``<=`` | Any version less than or | ``<=3.1``: any version |
|
|
|
|
|
| | equal to the specified version. | less than or equal to ``3.1``. |
|
|
|
|
|
+----------+---------------------------------+--------------------------------+
|
|
|
|
|
| ``>=`` | Any version greater than or | ``>=3.1``: |
|
|
|
|
|
| | equal to the specified version. | version ``3.1`` and greater. |
|
|
|
|
|
+----------+---------------------------------+--------------------------------+
|
|
|
|
|
| ``==`` | Exactly the specified version. | ``==3.1``: only ``3.1``. |
|
|
|
|
|
+----------+---------------------------------+--------------------------------+
|
|
|
|
|
| ``!=`` | Any version not equal | ``!=3.1``: any version |
|
|
|
|
|
| | to the specified version. | other than ``3.1``. |
|
|
|
|
|
+----------+---------------------------------+--------------------------------+
|
|
|
|
|
| ``~=`` | Any compatible release. | ``~=3.1``: version ``3.1`` |
|
|
|
|
|
| | Compatible releases are | or later, but not |
|
|
|
|
|
| | releases that are within the | version ``4.0`` or later. |
|
|
|
|
|
| | same major or minor version, | ``~=3.1.2``: version ``3.1.2`` |
|
|
|
|
|
| | assuming the package author | or later, but not |
|
|
|
|
|
| | is using semantic versioning. | version ``3.2.0`` or later. |
|
|
|
|
|
+----------+---------------------------------+--------------------------------+
|
|
|
|
|
| ``*`` | Can be used at the end of | ``==3.1.*``: any version |
|
|
|
|
|
| | a version number to represent | that starts with ``3.1``. |
|
|
|
|
|
| | *all*, | Equivalent to ``~=3.1.0``. |
|
|
|
|
|
+----------+---------------------------------+--------------------------------+
|
2020-06-24 06:49:20 +02:00
|
|
|
|
|
|
|
|
|
The detailed specification of supported comparison operators can be
|
|
|
|
|
found in :pep:`440`.
|
|
|
|
|
|
|
|
|
|
Possible solutions
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
The solution to your error will depend on your individual use case. Here
|
|
|
|
|
are some things to try:
|
|
|
|
|
|
|
|
|
|
1. Audit your top level requirements
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
As a first step it is useful to audit your project and remove any
|
|
|
|
|
unnecessary or out of date requirements (e.g. from your ``setup.py`` or
|
|
|
|
|
``requirements.txt`` files). Removing these can significantly reduce the
|
|
|
|
|
complexity of your dependency tree, thereby reducing opportunities for
|
|
|
|
|
conflicts to occur.
|
|
|
|
|
|
|
|
|
|
2. Loosen your top level requirements
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
Sometimes the packages that you have asked pip to install are
|
|
|
|
|
incompatible because you have been too strict when you specified the
|
|
|
|
|
package version.
|
|
|
|
|
|
|
|
|
|
In our first example both ``package_coffee`` and ``package_tea`` have been
|
|
|
|
|
*pinned* to use specific versions
|
|
|
|
|
(``package_coffee==0.44.1b0 package_tea==4.3.0``).
|
|
|
|
|
|
|
|
|
|
To find a version of both ``package_coffee`` and ``package_tea`` that depend on
|
|
|
|
|
the same version of ``package_water``, you might consider:
|
|
|
|
|
|
|
|
|
|
- Loosening the range of packages that you are prepared to install
|
|
|
|
|
(e.g. ``pip install "package_coffee>0.44.*" "package_tea>4.0.0"``)
|
|
|
|
|
- Asking pip to install *any* version of ``package_coffee`` and ``package_tea``
|
|
|
|
|
by removing the version specifiers altogether (e.g.
|
2020-07-29 13:07:32 +02:00
|
|
|
|
``python -m pip install package_coffee package_tea``)
|
2020-06-24 06:49:20 +02:00
|
|
|
|
|
|
|
|
|
In the second case, pip will automatically find a version of both
|
|
|
|
|
``package_coffee`` and ``package_tea`` that depend on the same version of
|
|
|
|
|
``package_water``, installing:
|
|
|
|
|
|
|
|
|
|
- ``package_coffee 0.46.0b0``, which depends on ``package_water 2.6.1``
|
|
|
|
|
- ``package_tea 4.3.0`` which *also* depends on ``package_water 2.6.1``
|
|
|
|
|
|
|
|
|
|
If you want to prioritize one package over another, you can add version
|
2020-07-29 13:07:32 +02:00
|
|
|
|
specifiers to *only* the more important package:
|
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-07-30 09:03:16 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
python -m pip install package_coffee==0.44.1b0 package_tea
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-07-29 13:07:32 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-06-24 06:49:20 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
py -m pip install package_coffee==0.44.1b0 package_tea
|
2020-06-24 06:49:20 +02:00
|
|
|
|
|
|
|
|
|
This will result in:
|
|
|
|
|
|
|
|
|
|
- ``package_coffee 0.44.1b0``, which depends on ``package_water 2.6.1``
|
|
|
|
|
- ``package_tea 4.1.3`` which also depends on ``package_water 2.6.1``
|
|
|
|
|
|
|
|
|
|
Now that you have resolved the issue, you can repin the compatible
|
|
|
|
|
package versions as required.
|
|
|
|
|
|
|
|
|
|
3. Loosen the requirements of your dependencies
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
Assuming that you cannot resolve the conflict by loosening the version
|
|
|
|
|
of the package you require (as above), you can try to fix the issue on
|
|
|
|
|
your *dependency* by:
|
|
|
|
|
|
|
|
|
|
- Requesting that the package maintainers loosen *their* dependencies
|
|
|
|
|
- Forking the package and loosening the dependencies yourself
|
|
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
If you choose to fork the package yourself, you are *opting out* of
|
|
|
|
|
any support provided by the package maintainers. Proceed at your own risk!
|
|
|
|
|
|
|
|
|
|
4. All requirements are loose, but a solution does not exist
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
Sometimes it's simply impossible to find a combination of package
|
|
|
|
|
versions that do not conflict. Welcome to `dependency hell`_.
|
|
|
|
|
|
|
|
|
|
In this situation, you could consider:
|
|
|
|
|
|
|
|
|
|
- Using an alternative package, if that is acceptable for your project.
|
|
|
|
|
See `Awesome Python`_ for similar packages.
|
|
|
|
|
- Refactoring your project to reduce the number of dependencies (for
|
|
|
|
|
example, by breaking up a monolithic code base into smaller pieces)
|
|
|
|
|
|
2020-10-28 12:56:45 +01:00
|
|
|
|
.. _`Getting help`:
|
|
|
|
|
|
2020-06-24 06:49:20 +02:00
|
|
|
|
Getting help
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
If none of the suggestions above work for you, we recommend that you ask
|
|
|
|
|
for help on:
|
|
|
|
|
|
|
|
|
|
- `Python user Discourse`_
|
|
|
|
|
- `Python user forums`_
|
|
|
|
|
- `Python developers Slack channel`_
|
|
|
|
|
- `Python IRC`_
|
|
|
|
|
- `Stack Overflow`_
|
|
|
|
|
|
|
|
|
|
See `"How do I ask a good question?"`_ for tips on asking for help.
|
|
|
|
|
|
|
|
|
|
Unfortunately, **the pip team cannot provide support for individual
|
|
|
|
|
dependency conflict errors**. Please *only* open a ticket on the `pip
|
|
|
|
|
issue tracker`_ if you believe that your problem has exposed a bug in pip.
|
|
|
|
|
|
2020-07-31 14:15:23 +02:00
|
|
|
|
.. _dependency hell: https://en.wikipedia.org/wiki/Dependency_hell
|
2020-06-24 06:49:20 +02:00
|
|
|
|
.. _Awesome Python: https://python.libhunt.com/
|
|
|
|
|
.. _Python user Discourse: https://discuss.python.org/c/users/7
|
|
|
|
|
.. _Python user forums: https://www.python.org/community/forums/
|
|
|
|
|
.. _Python developers Slack channel: https://pythondev.slack.com/
|
|
|
|
|
.. _Python IRC: https://www.python.org/community/irc/
|
|
|
|
|
.. _Stack Overflow: https://stackoverflow.com/questions/tagged/python
|
|
|
|
|
.. _"How do I ask a good question?": https://stackoverflow.com/help/how-to-ask
|
|
|
|
|
.. _pip issue tracker: https://github.com/pypa/pip/issues
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2020-10-26 13:23:07 +01:00
|
|
|
|
.. _`Dependency resolution backtracking`:
|
2020-08-19 03:57:08 +02:00
|
|
|
|
|
2020-10-21 17:50:04 +02:00
|
|
|
|
Dependency resolution backtracking
|
|
|
|
|
==================================
|
|
|
|
|
|
|
|
|
|
Or more commonly known as *"Why does pip download multiple versions of
|
2020-10-23 15:14:19 +02:00
|
|
|
|
the same package over and over again during an install?"*.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-23 15:14:19 +02:00
|
|
|
|
The purpose of this section is to provide explanation of why
|
|
|
|
|
backtracking happens, and practical suggestions to pip users who
|
2020-10-26 13:23:07 +01:00
|
|
|
|
encounter it during a ``pip install``.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
|
|
|
|
What is backtracking?
|
|
|
|
|
---------------------
|
|
|
|
|
|
2020-10-23 15:14:19 +02:00
|
|
|
|
Backtracking is not a bug, or an unexpected behaviour. It is part of the
|
|
|
|
|
way pip's dependency resolution process works.
|
|
|
|
|
|
2020-10-21 17:50:04 +02:00
|
|
|
|
During a pip install (e.g. ``pip install tea``), pip needs to work out
|
2020-10-26 13:23:07 +01:00
|
|
|
|
the package's dependencies (e.g. ``spoon``, ``hot-water``, ``cup`` etc), the
|
2020-10-28 14:30:04 +01:00
|
|
|
|
versions of each of these packages it needs to install. For each package
|
|
|
|
|
pip needs to decide which version is a good candidate to install.
|
2020-10-26 10:14:34 +01:00
|
|
|
|
|
2020-10-26 13:23:07 +01:00
|
|
|
|
A "good candidate" means a version of each package that is compatible with all
|
|
|
|
|
the other package versions being installed at the same time.
|
2020-10-23 15:14:19 +02:00
|
|
|
|
|
|
|
|
|
In the case where a package has a lot of versions, arriving at a good
|
|
|
|
|
candidate can take a lot of time. (The amount of time depends on the
|
2020-10-26 10:14:34 +01:00
|
|
|
|
package size, the number of versions pip must try, and other concerns.)
|
2020-10-23 15:14:19 +02:00
|
|
|
|
|
|
|
|
|
How does backtracking work?
|
2020-11-11 11:20:29 +01:00
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
2020-10-23 15:14:19 +02:00
|
|
|
|
|
2020-10-28 14:30:04 +01:00
|
|
|
|
When doing a pip install, pip starts by making assumptions about the
|
2020-10-28 12:56:45 +01:00
|
|
|
|
packages it needs to install. During the install process it needs to check these
|
2020-10-26 10:14:34 +01:00
|
|
|
|
assumptions as it goes along.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-28 14:30:04 +01:00
|
|
|
|
When pip finds that an assumption is incorrect, it has to try another approach
|
2020-10-26 10:14:34 +01:00
|
|
|
|
(backtrack), which means discarding some of the work that has already been done,
|
|
|
|
|
and going back to choose another path.
|
|
|
|
|
|
2020-10-26 13:23:07 +01:00
|
|
|
|
For example; The user requests ``pip install tea``. ```tea`` has dependencies of
|
|
|
|
|
``cup``, ``hot-water``, ``spoon`` amongst others.
|
2020-10-23 15:14:19 +02:00
|
|
|
|
|
2020-10-26 13:23:07 +01:00
|
|
|
|
pip starts by installing a version of ``cup``. If it finds out it isn’t
|
|
|
|
|
compatible (with the other package versions) it needs to “go back”
|
|
|
|
|
(backtrack) and download an older version.
|
2020-10-26 10:14:34 +01:00
|
|
|
|
|
|
|
|
|
It then tries to install that version. If it is successful, it will continue
|
|
|
|
|
onto the next package. If not it will continue to backtrack until it finds a
|
|
|
|
|
compatible version.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
|
|
|
|
This backtrack behaviour can end in 2 ways - either 1) it will
|
2020-10-28 12:56:45 +01:00
|
|
|
|
successfully find a set of packages it can install (good news!), or 2) it will
|
2020-10-28 14:30:04 +01:00
|
|
|
|
eventually display a `resolution impossible <https://pip.pypa.io/en/latest/user_guide/#id35>`__ error
|
2020-10-23 15:14:19 +02:00
|
|
|
|
message (not so good).
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
|
|
|
|
If pip starts backtracking during dependency resolution, it does not
|
|
|
|
|
know how long it will backtrack, and how much computation would be
|
2020-10-26 13:23:07 +01:00
|
|
|
|
needed. For the user this means it can take a long time to complete.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-23 15:14:19 +02:00
|
|
|
|
Why does backtracking occur?
|
|
|
|
|
----------------------------
|
|
|
|
|
|
2020-10-26 10:14:34 +01:00
|
|
|
|
With the release of the new resolver (:ref:`Resolver changes 2020`), pip is now
|
2020-10-28 12:56:45 +01:00
|
|
|
|
more strict in the package versions it installs when a user runs a
|
2020-10-26 10:14:34 +01:00
|
|
|
|
``pip install`` command.
|
|
|
|
|
|
|
|
|
|
Pip needs to backtrack because initially, it doesn't have all the information it
|
|
|
|
|
needs to work out the correct set of packages. This is because package indexes
|
|
|
|
|
don't provide full package dependency information before you have downloaded
|
|
|
|
|
the package.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-26 13:23:07 +01:00
|
|
|
|
This new resolver behaviour means that pip works harder to find out which
|
|
|
|
|
version of a package is a good candidate to install. It reduces the risk that
|
|
|
|
|
installing a new package will accidentally break an existing installed package,
|
2020-10-28 14:30:04 +01:00
|
|
|
|
and so reduces the risk that your environment gets messed up.
|
|
|
|
|
|
2020-10-21 17:50:04 +02:00
|
|
|
|
What does this behaviour look like?
|
|
|
|
|
-----------------------------------
|
|
|
|
|
|
2020-10-26 13:23:07 +01:00
|
|
|
|
Right now backtracking behaviour looks like this:
|
2020-10-23 15:14:19 +02:00
|
|
|
|
|
2020-10-21 17:50:04 +02:00
|
|
|
|
::
|
|
|
|
|
|
|
|
|
|
$ pip install tea==1.9.8
|
|
|
|
|
Collecting tea==1.9.8
|
2020-10-28 12:56:45 +01:00
|
|
|
|
Downloading tea-1.9.8-py2.py3-none-any.whl (346 kB)
|
|
|
|
|
|████████████████████████████████| 346 kB 10.4 MB/s
|
2020-10-21 17:50:04 +02:00
|
|
|
|
Collecting spoon==2.27.0
|
2020-10-28 12:56:45 +01:00
|
|
|
|
Downloading spoon-2.27.0-py2.py3-none-any.whl (312 kB)
|
|
|
|
|
|████████████████████████████████| 312 kB 19.2 MB/s
|
2020-10-21 17:50:04 +02:00
|
|
|
|
Collecting hot-water>=0.1.9
|
|
|
|
|
Downloading hot-water-0.1.13-py3-none-any.whl (9.3 kB)
|
|
|
|
|
Collecting cup>=1.6.0
|
2020-10-28 12:56:45 +01:00
|
|
|
|
Downloading cup-3.22.0-py2.py3-none-any.whl (397 kB)
|
|
|
|
|
|████████████████████████████████| 397 kB 28.2 MB/s
|
2020-10-21 17:50:04 +02:00
|
|
|
|
INFO: pip is looking at multiple versions of this package to determine
|
|
|
|
|
which version is compatible with other requirements.
|
|
|
|
|
This could take a while.
|
2020-10-28 12:56:45 +01:00
|
|
|
|
Downloading cup-3.21.0-py2.py3-none-any.whl (395 kB)
|
|
|
|
|
|████████████████████████████████| 395 kB 27.0 MB/s
|
|
|
|
|
Downloading cup-3.20.0-py2.py3-none-any.whl (394 kB)
|
|
|
|
|
|████████████████████████████████| 394 kB 24.4 MB/s
|
|
|
|
|
Downloading cup-3.19.1-py2.py3-none-any.whl (394 kB)
|
|
|
|
|
|████████████████████████████████| 394 kB 21.3 MB/s
|
|
|
|
|
Downloading cup-3.19.0-py2.py3-none-any.whl (394 kB)
|
|
|
|
|
|████████████████████████████████| 394 kB 26.2 MB/s
|
|
|
|
|
Downloading cup-3.18.0-py2.py3-none-any.whl (393 kB)
|
|
|
|
|
|████████████████████████████████| 393 kB 22.1 MB/s
|
|
|
|
|
Downloading cup-3.17.0-py2.py3-none-any.whl (382 kB)
|
|
|
|
|
|████████████████████████████████| 382 kB 23.8 MB/s
|
|
|
|
|
Downloading cup-3.16.0-py2.py3-none-any.whl (376 kB)
|
|
|
|
|
|████████████████████████████████| 376 kB 27.5 MB/s
|
|
|
|
|
Downloading cup-3.15.1-py2.py3-none-any.whl (385 kB)
|
|
|
|
|
|████████████████████████████████| 385 kB 30.4 MB/s
|
2020-10-21 17:50:04 +02:00
|
|
|
|
INFO: pip is looking at multiple versions of this package to determine
|
|
|
|
|
which version is compatible with other requirements.
|
|
|
|
|
This could take a while.
|
2020-10-28 12:56:45 +01:00
|
|
|
|
Downloading cup-3.15.0-py2.py3-none-any.whl (378 kB)
|
|
|
|
|
|████████████████████████████████| 378 kB 21.4 MB/s
|
|
|
|
|
Downloading cup-3.14.0-py2.py3-none-any.whl (372 kB)
|
|
|
|
|
|████████████████████████████████| 372 kB 21.1 MB/s
|
|
|
|
|
Downloading cup-3.13.1-py2.py3-none-any.whl (381 kB)
|
|
|
|
|
|████████████████████████████████| 381 kB 21.8 MB/s
|
2020-10-21 17:50:04 +02:00
|
|
|
|
This is taking longer than usual. You might need to provide the
|
|
|
|
|
dependency resolver with stricter constraints to reduce runtime.
|
|
|
|
|
If you want to abort this run, you can press Ctrl + C to do so.
|
2020-10-28 12:56:45 +01:00
|
|
|
|
Downloading cup-3.13.0-py2.py3-none-any.whl (374 kB)
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-26 10:14:34 +01:00
|
|
|
|
In the above sample output, pip had to download multiple versions of
|
2020-11-11 11:20:29 +01:00
|
|
|
|
package ``cup`` - cup-3.22.0 to cup-3.13.0 - to find a version that will be
|
|
|
|
|
compatible with the other packages - ``spoon``, ``hot-water``, etc.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-28 12:56:45 +01:00
|
|
|
|
These multiple ``Downloading cup-version`` lines show pip backtracking.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-26 10:14:34 +01:00
|
|
|
|
Possible ways to reduce backtracking occurring
|
2020-11-11 11:20:29 +01:00
|
|
|
|
----------------------------------------------
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-23 15:14:19 +02:00
|
|
|
|
It's important to mention backtracking behaviour is expected during a
|
|
|
|
|
``pip install`` process. What pip is trying to do is complicated - it is
|
|
|
|
|
working through potentially millions of package versions to identify the
|
2020-10-26 10:14:34 +01:00
|
|
|
|
compatible versions.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-23 15:14:19 +02:00
|
|
|
|
There is no guaranteed solution to backtracking but you can reduce it -
|
|
|
|
|
here are a number of ways.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-23 15:14:19 +02:00
|
|
|
|
.. _1-allow-pip-to-complete-its-backtracking:
|
|
|
|
|
|
|
|
|
|
1. Allow pip to complete its backtracking
|
2020-11-11 11:20:29 +01:00
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
2020-10-23 15:14:19 +02:00
|
|
|
|
|
|
|
|
|
In most cases, pip will complete the backtracking process successfully.
|
|
|
|
|
It is possible this could take a very long time to complete - this may
|
|
|
|
|
not be the preferred option.
|
|
|
|
|
|
|
|
|
|
However there is a possibility pip will not be able to find a set of
|
|
|
|
|
compatible versions.
|
|
|
|
|
|
|
|
|
|
If you'd prefer not to wait, you can interrupt pip (ctrl and c) and use
|
2020-10-30 12:31:01 +01:00
|
|
|
|
:ref:`Constraints Files`: to reduce the number of package versions it tries.
|
2020-10-23 15:14:19 +02:00
|
|
|
|
|
|
|
|
|
.. _2-reduce-the-versions-of-the-backtracking-package:
|
|
|
|
|
|
2020-10-30 12:35:52 +01:00
|
|
|
|
2. Reduce the number of versions pip will try to backtrack through
|
2020-11-11 11:20:29 +01:00
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
2020-10-23 15:14:19 +02:00
|
|
|
|
|
|
|
|
|
If pip is backtracking more than you'd like, the next option is to
|
|
|
|
|
constrain the number of package versions it tries.
|
|
|
|
|
|
|
|
|
|
A first good candidate for this constraining is the package(s) it is
|
|
|
|
|
backtracking on (e.g. in the above example - ``cup``).
|
|
|
|
|
|
2020-10-23 15:16:39 +02:00
|
|
|
|
You could try:
|
2020-10-23 15:14:19 +02:00
|
|
|
|
|
2020-10-26 10:14:34 +01:00
|
|
|
|
``pip install tea "cup > 3.13"``
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-23 15:14:19 +02:00
|
|
|
|
This will reduce the number of versions of ``cup`` it tries, and
|
|
|
|
|
possibly reduce the time pip takes to install.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-26 10:14:34 +01:00
|
|
|
|
There is a possibility that if you're wrong (in this case an older
|
2020-10-23 15:14:19 +02:00
|
|
|
|
version would have worked) then you missed the chance to use it. This
|
|
|
|
|
can be trial and error.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-23 15:14:19 +02:00
|
|
|
|
.. _3-use-constraint-files-or-lockfiles:
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-23 15:14:19 +02:00
|
|
|
|
3. Use constraint files or lockfiles
|
2020-11-11 11:20:29 +01:00
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-23 15:14:19 +02:00
|
|
|
|
This option is a progression of 2 above. It requires users to know how
|
|
|
|
|
to inspect:
|
|
|
|
|
|
2020-10-28 14:30:04 +01:00
|
|
|
|
- the packages they're trying to install
|
2020-10-23 15:14:19 +02:00
|
|
|
|
- the package release frequency and compatibility policies
|
|
|
|
|
- their release notes and changelogs from past versions
|
|
|
|
|
|
2020-10-26 10:14:34 +01:00
|
|
|
|
During deployment, you can create a lockfile stating the exact package and
|
|
|
|
|
version number for for each dependency of that package. You can create this
|
2020-10-23 15:14:19 +02:00
|
|
|
|
with `pip-tools <https://github.com/jazzband/pip-tools/>`__.
|
|
|
|
|
|
|
|
|
|
This means the "work" is done once during development process, and so
|
|
|
|
|
will save users this work during deployment.
|
|
|
|
|
|
|
|
|
|
The pip team is not available to provide support in helping you create a
|
|
|
|
|
suitable constraints file.
|
|
|
|
|
|
|
|
|
|
.. _4-be-more-strict-on-package-dependencies-during-development:
|
|
|
|
|
|
|
|
|
|
4. Be more strict on package dependencies during development
|
2020-11-11 11:20:29 +01:00
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
2020-10-23 15:14:19 +02:00
|
|
|
|
|
|
|
|
|
For package maintainers during the development, give pip some help by
|
|
|
|
|
creating constraint files for the dependency tree. This will reduce the
|
|
|
|
|
number of versions it will try.
|
|
|
|
|
|
|
|
|
|
Getting help
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
If none of the suggestions above work for you, we recommend that you ask
|
2020-10-28 14:30:04 +01:00
|
|
|
|
for help and you've got `a number of options :ref:`Getting help`.
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2020-10-26 13:23:07 +01:00
|
|
|
|
.. _`Using pip from your program`:
|
2020-10-21 17:50:04 +02:00
|
|
|
|
|
2017-09-28 23:15:51 +02:00
|
|
|
|
Using pip from your program
|
2020-02-11 14:00:03 +01:00
|
|
|
|
===========================
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
As noted previously, pip is a command line program. While it is implemented in
|
|
|
|
|
Python, and so is available from your Python code via ``import pip``, you must
|
|
|
|
|
not use pip's internal APIs in this way. There are a number of reasons for this:
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
#. The pip code assumes that is in sole control of the global state of the
|
|
|
|
|
program.
|
|
|
|
|
pip manages things like the logging system configuration, or the values of
|
|
|
|
|
the standard IO streams, without considering the possibility that user code
|
|
|
|
|
might be affected.
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
#. pip's code is *not* thread safe. If you were to run pip in a thread, there
|
|
|
|
|
is no guarantee that either your code or pip's would work as you expect.
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
#. pip assumes that once it has finished its work, the process will terminate.
|
|
|
|
|
It doesn't need to handle the possibility that other code will continue to
|
|
|
|
|
run after that point, so (for example) calling pip twice in the same process
|
|
|
|
|
is likely to have issues.
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
2019-09-24 14:07:54 +02:00
|
|
|
|
This does not mean that the pip developers are opposed in principle to the idea
|
|
|
|
|
that pip could be used as a library - it's just that this isn't how it was
|
|
|
|
|
written, and it would be a lot of work to redesign the internals for use as a
|
|
|
|
|
library, handling all of the above issues, and designing a usable, robust and
|
|
|
|
|
stable API that we could guarantee would remain available across multiple
|
|
|
|
|
releases of pip. And we simply don't currently have the resources to even
|
|
|
|
|
consider such a task.
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
|
|
|
|
What this means in practice is that everything inside of pip is considered an
|
2019-09-24 14:07:54 +02:00
|
|
|
|
implementation detail. Even the fact that the import name is ``pip`` is subject
|
|
|
|
|
to change without notice. While we do try not to break things as much as
|
|
|
|
|
possible, all the internal APIs can change at any time, for any reason. It also
|
|
|
|
|
means that we generally *won't* fix issues that are a result of using pip in an
|
|
|
|
|
unsupported way.
|
|
|
|
|
|
|
|
|
|
It should also be noted that installing packages into ``sys.path`` in a running
|
|
|
|
|
Python process is something that should only be done with care. The import
|
|
|
|
|
system caches certain data, and installing new packages while a program is
|
|
|
|
|
running may not always behave as expected. In practice, there is rarely an
|
|
|
|
|
issue, but it is something to be aware of.
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
|
|
|
|
Having said all of the above, it is worth covering the options available if you
|
|
|
|
|
decide that you do want to run pip from within your program. The most reliable
|
2019-09-24 14:07:54 +02:00
|
|
|
|
approach, and the one that is fully supported, is to run pip in a subprocess.
|
|
|
|
|
This is easily done using the standard ``subprocess`` module::
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
|
|
|
|
subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'my_package'])
|
|
|
|
|
|
2020-03-28 12:15:25 +01:00
|
|
|
|
If you want to process the output further, use one of the other APIs in the module.
|
|
|
|
|
We are using `freeze`_ here which outputs installed packages in requirements format.::
|
2017-09-28 23:15:51 +02:00
|
|
|
|
|
|
|
|
|
reqs = subprocess.check_output([sys.executable, '-m', 'pip', 'freeze'])
|
|
|
|
|
|
|
|
|
|
If you don't want to use pip's command line functionality, but are rather
|
|
|
|
|
trying to implement code that works with Python packages, their metadata, or
|
|
|
|
|
PyPI, then you should consider other, supported, packages that offer this type
|
|
|
|
|
of ability. Some examples that you could consider include:
|
|
|
|
|
|
|
|
|
|
* ``packaging`` - Utilities to work with standard package metadata (versions,
|
|
|
|
|
requirements, etc.)
|
|
|
|
|
|
|
|
|
|
* ``setuptools`` (specifically ``pkg_resources``) - Functions for querying what
|
|
|
|
|
packages the user has installed on their system.
|
|
|
|
|
|
|
|
|
|
* ``distlib`` - Packaging and distribution utilities (including functions for
|
|
|
|
|
interacting with PyPI).
|
2020-03-28 12:15:25 +01:00
|
|
|
|
|
2020-07-28 16:00:40 +02:00
|
|
|
|
.. _`Resolver changes 2020`:
|
|
|
|
|
|
2020-07-28 15:05:15 +02:00
|
|
|
|
Changes to the pip dependency resolver in 20.2 (2020)
|
|
|
|
|
=====================================================
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
2020-07-23 19:12:43 +02:00
|
|
|
|
pip 20.1 included an alpha version of the new resolver (hidden behind
|
2020-07-30 19:58:47 +02:00
|
|
|
|
an optional ``--unstable-feature=resolver`` flag). pip 20.2 removes
|
|
|
|
|
that flag, and includes a robust beta of the new resolver (hidden
|
|
|
|
|
behind an optional ``--use-feature=2020-resolver`` flag) that we
|
|
|
|
|
encourage you to test. We will continue to improve the pip dependency
|
|
|
|
|
resolver in response to testers' feedback. Please give us feedback
|
|
|
|
|
through the `resolver testing survey`_. This will help us prepare to
|
|
|
|
|
release pip 20.3, with the new resolver on by default, in October.
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
Watch out for
|
|
|
|
|
-------------
|
|
|
|
|
|
2020-07-23 19:12:43 +02:00
|
|
|
|
The big change in this release is to the pip dependency resolver
|
|
|
|
|
within pip.
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
Computers need to know the right order to install pieces of software
|
2020-09-23 16:21:42 +02:00
|
|
|
|
("to install ``x``, you need to install ``y`` first"). So, when Python
|
2020-06-24 06:20:14 +02:00
|
|
|
|
programmers share software as packages, they have to precisely describe
|
|
|
|
|
those installation prerequisites, and pip needs to navigate tricky
|
|
|
|
|
situations where it's getting conflicting instructions. This new
|
|
|
|
|
dependency resolver will make pip better at handling that tricky
|
2020-07-28 17:22:57 +02:00
|
|
|
|
logic, and make pip easier for you to use and troubleshoot.
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
The most significant changes to the resolver are:
|
|
|
|
|
|
|
|
|
|
* It will **reduce inconsistency**: it will *no longer install a
|
2020-07-28 16:16:58 +02:00
|
|
|
|
combination of packages that is mutually inconsistent*. In older
|
|
|
|
|
versions of pip, it is possible for pip to install a package which
|
|
|
|
|
does not satisfy the declared requirements of another installed
|
|
|
|
|
package. For example, in pip 20.0, ``pip install "six<1.12"
|
|
|
|
|
"virtualenv==20.0.2"`` does the wrong thing, “successfully” installing
|
|
|
|
|
``six==1.11``, even though ``virtualenv==20.0.2`` requires
|
|
|
|
|
``six>=1.12.0,<2`` (`defined here
|
|
|
|
|
<https://github.com/pypa/virtualenv/blob/20.0.2/setup.cfg#L42-L50>`__).
|
|
|
|
|
The new resolver, instead, outright rejects installing anything if it
|
|
|
|
|
gets that input.
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
* It will be **stricter** - if you ask pip to install two packages with
|
2020-07-28 16:16:58 +02:00
|
|
|
|
incompatible requirements, it will refuse (rather than installing a
|
|
|
|
|
broken combination, like it did in previous versions).
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
So, if you have been using workarounds to force pip to deal with
|
|
|
|
|
incompatible or inconsistent requirements combinations, now's a good
|
|
|
|
|
time to fix the underlying problem in the packages, because pip will
|
|
|
|
|
be stricter from here on out.
|
|
|
|
|
|
2020-06-30 05:05:14 +02:00
|
|
|
|
This also means that, when you run a ``pip install`` command, pip only
|
|
|
|
|
considers the packages you are installing in that command, and may
|
|
|
|
|
break already-installed packages. It will not guarantee that your
|
|
|
|
|
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``
|
|
|
|
|
you get will be different than it would be if you had run ``pip
|
2020-07-28 17:22:57 +02:00
|
|
|
|
install x y`` in a single command. We would like your thoughts on what
|
|
|
|
|
pip's behavior should be; please answer `our survey on upgrades that
|
|
|
|
|
create conflicts`_.
|
2020-06-30 05:05:14 +02:00
|
|
|
|
|
2020-07-28 15:33:31 +02:00
|
|
|
|
We are also changing our support for :ref:`Constraints Files`:
|
2020-06-24 06:35:57 +02:00
|
|
|
|
|
2020-07-28 15:50:46 +02:00
|
|
|
|
* Unnamed requirements are not allowed as constraints (see :issue:`6628` and :issue:`8210`)
|
|
|
|
|
* Links are not allowed as constraints (see :issue:`8253`)
|
|
|
|
|
* Constraints cannot have extras (see :issue:`6628`)
|
2020-06-24 06:35:57 +02:00
|
|
|
|
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
How to test
|
|
|
|
|
-----------
|
|
|
|
|
|
2020-07-23 19:12:43 +02:00
|
|
|
|
1. **Install pip 20.2** with ``python -m pip install --upgrade pip``.
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
2020-07-28 15:29:23 +02:00
|
|
|
|
2. **Validate your current environment** by running ``pip check``. This
|
2020-06-24 06:20:14 +02:00
|
|
|
|
will report if you have any inconsistencies in your set of installed
|
|
|
|
|
packages. Having a clean installation will make it much less likely
|
|
|
|
|
that you will hit issues when the new resolver is released (and may
|
|
|
|
|
address hidden problems in your current environment!). If you run
|
|
|
|
|
``pip check`` and run into stuff you can’t figure out, please `ask
|
2020-07-28 15:33:31 +02:00
|
|
|
|
for help in our issue tracker or chat <https://pip.pypa.io/>`__.
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
2020-07-28 15:23:07 +02:00
|
|
|
|
3. **Test the new version of pip** (see below). To test the new
|
|
|
|
|
resolver, use the ``--use-feature=2020-resolver`` flag, as in:
|
|
|
|
|
|
|
|
|
|
``pip install example --use-feature=2020-resolver``
|
|
|
|
|
|
|
|
|
|
The more feedback we can get, the more we can make sure that the
|
|
|
|
|
final release is solid. (Only try the new resolver **in a
|
|
|
|
|
non-production environment**, though - it isn't ready for you to
|
|
|
|
|
rely on in production!)
|
|
|
|
|
|
|
|
|
|
While we have tried to make sure that pip’s test suite covers as
|
|
|
|
|
many cases as we can, we are very aware that there are people using
|
|
|
|
|
pip with many different workflows and build processes, and we will
|
|
|
|
|
not be able to cover all of those without your help.
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
- If you use pip to install your software, try out the new resolver
|
|
|
|
|
and let us know if it works for you with ``pip install``. Try:
|
2020-07-28 16:21:52 +02:00
|
|
|
|
|
2020-08-24 10:42:31 +02:00
|
|
|
|
- installing several packages simultaneously
|
|
|
|
|
- re-creating an environment using a ``requirements.txt`` file
|
|
|
|
|
- using ``pip install --force-reinstall`` to check whether
|
|
|
|
|
it does what you think it should
|
|
|
|
|
- using constraints files
|
2020-07-28 16:21:52 +02:00
|
|
|
|
|
2020-06-24 06:20:14 +02:00
|
|
|
|
- If you have a build pipeline that depends on pip installing your
|
|
|
|
|
dependencies for you, check that the new resolver does what you
|
|
|
|
|
need.
|
2020-09-30 13:10:09 +02:00
|
|
|
|
|
|
|
|
|
- If you'd like pip to default to using the new resolver, run ``pip
|
|
|
|
|
config set global.use-feature 2020-resolver`` (for more on that
|
|
|
|
|
and the alternate ``PIP_USE_FEATURE`` environment variable
|
|
|
|
|
option, see `issue 8661`_).
|
|
|
|
|
|
2020-06-24 06:20:14 +02:00
|
|
|
|
- Run your project’s CI (test suite, build process, etc.) using the
|
|
|
|
|
new resolver, and let us know of any issues.
|
|
|
|
|
- If you have encountered resolver issues with pip in the past,
|
|
|
|
|
check whether the new resolver fixes them. Also, let us know if
|
|
|
|
|
the new resolver has issues with any workarounds you put in to
|
|
|
|
|
address the current resolver’s limitations. We’ll need to ensure
|
|
|
|
|
that people can transition off such workarounds smoothly.
|
|
|
|
|
- If you develop or support a tool that wraps pip or uses it to
|
|
|
|
|
deliver part of your functionality, please test your integration
|
2020-07-23 19:12:43 +02:00
|
|
|
|
with pip 20.2.
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
2020-07-28 15:23:07 +02:00
|
|
|
|
4. **Please report bugs** through the `resolver testing survey`_.
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
Setups we might need more testing on
|
|
|
|
|
------------------------------------
|
|
|
|
|
|
2020-07-28 15:05:15 +02:00
|
|
|
|
* Windows, including Windows Subsystem for Linux (WSL)
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
* Macintosh
|
|
|
|
|
|
|
|
|
|
* Debian, Fedora, Red Hat, CentOS, Mint, Arch, Raspbian, Gentoo
|
|
|
|
|
|
2020-07-28 15:05:15 +02:00
|
|
|
|
* non-Latin localized filesystems and OSes, such as Japanese, Chinese, and Korean, and right-to-left such as Hebrew, Urdu, and Arabic
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
* Multi-user installations
|
|
|
|
|
|
2020-07-28 15:05:15 +02:00
|
|
|
|
* Requirements files with 100+ packages
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
2020-07-28 17:22:57 +02:00
|
|
|
|
* An installation workflow that involves multiple requirements files
|
2020-07-28 15:23:07 +02:00
|
|
|
|
|
2020-07-28 15:29:23 +02:00
|
|
|
|
* Requirements files that include hashes (:ref:`hash-checking mode`)
|
2020-07-28 15:33:31 +02:00
|
|
|
|
or pinned dependencies (perhaps as output from ``pip-compile`` within
|
2020-07-28 15:29:23 +02:00
|
|
|
|
``pip-tools``)
|
|
|
|
|
|
|
|
|
|
* Using :ref:`Constraints Files`
|
2020-07-28 15:05:15 +02:00
|
|
|
|
|
|
|
|
|
* Continuous integration/continuous deployment setups
|
|
|
|
|
|
2020-07-28 15:23:07 +02:00
|
|
|
|
* Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per :ref:`VCS Support`
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
|
|
|
|
* Installing from source code held in local directories
|
|
|
|
|
|
|
|
|
|
* Using the most recent versions of Python 3.6, 3.7, 3.8, and 3.9
|
|
|
|
|
|
2020-07-28 15:23:07 +02:00
|
|
|
|
* PyPy
|
|
|
|
|
|
2020-06-24 06:20:14 +02:00
|
|
|
|
* Customized terminals (where you have modified how error messages and standard output display)
|
|
|
|
|
|
2020-07-28 15:23:07 +02:00
|
|
|
|
Examples to try
|
|
|
|
|
^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
Install:
|
|
|
|
|
|
|
|
|
|
* `tensorflow`_
|
|
|
|
|
* ``hacking``
|
|
|
|
|
* ``pycodestyle``
|
|
|
|
|
* ``pandas``
|
|
|
|
|
* ``tablib``
|
|
|
|
|
* ``elasticsearch`` and ``requests`` together
|
|
|
|
|
* ``six`` and ``cherrypy`` together
|
|
|
|
|
* ``pip install flake8-import-order==0.17.1 flake8==3.5.0 --use-feature=2020-resolver``
|
|
|
|
|
* ``pip install tornado==5.0 sprockets.http==1.5.0 --use-feature=2020-resolver``
|
|
|
|
|
|
|
|
|
|
Try:
|
|
|
|
|
|
|
|
|
|
* ``pip install``
|
|
|
|
|
* ``pip uninstall``
|
|
|
|
|
* ``pip check``
|
|
|
|
|
* ``pip cache``
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Tell us about
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
Specific things we'd love to get feedback on:
|
|
|
|
|
|
|
|
|
|
* Cases where the new resolver produces the wrong result,
|
|
|
|
|
obviously. We hope there won't be too many of these, but we'd like
|
|
|
|
|
to trap such bugs now.
|
|
|
|
|
|
|
|
|
|
* Cases where the resolver produced an error when you believe it
|
|
|
|
|
should have been able to work out what to do.
|
|
|
|
|
|
|
|
|
|
* Cases where the resolver gives an error because there's a problem
|
|
|
|
|
with your requirements, but you need better information to work out
|
|
|
|
|
what's wrong.
|
|
|
|
|
|
|
|
|
|
* If you have workarounds to address issues with the current resolver,
|
|
|
|
|
does the new resolver let you remove those workarounds? Tell us!
|
|
|
|
|
|
2020-07-28 16:00:40 +02:00
|
|
|
|
Please let us know through the `resolver testing survey`_.
|
2020-07-28 15:23:07 +02:00
|
|
|
|
|
2020-08-03 16:27:28 +02:00
|
|
|
|
Deprecation timeline
|
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
|
|
We plan for the resolver changeover to proceed as follows, using
|
|
|
|
|
:ref:`Feature Flags` and following our :ref:`Release Cadence`:
|
|
|
|
|
|
|
|
|
|
* pip 20.2: a beta of the new resolver is available, opt-in, using
|
|
|
|
|
the flag ``--use-feature=2020-resolver``. pip defaults to
|
|
|
|
|
legacy behavior.
|
|
|
|
|
|
|
|
|
|
* pip 20.3: pip defaults to the new resolver, but a user can opt-out
|
|
|
|
|
and choose the old resolver behavior, using the flag
|
|
|
|
|
``--use-deprecated=legacy-resolver``.
|
|
|
|
|
|
|
|
|
|
* pip 21.0: pip uses new resolver, and the old resolver is no longer
|
|
|
|
|
available.
|
|
|
|
|
|
|
|
|
|
Since this work will not change user-visible behavior described in the
|
|
|
|
|
pip documentation, this change is not covered by the :ref:`Deprecation
|
|
|
|
|
Policy`.
|
|
|
|
|
|
2020-07-28 15:23:07 +02:00
|
|
|
|
Context and followup
|
|
|
|
|
--------------------
|
|
|
|
|
|
2020-07-28 16:00:40 +02:00
|
|
|
|
As discussed in `our announcement on the PSF blog`_, the pip team are
|
|
|
|
|
in the process of developing a new "dependency resolver" (the part of
|
2020-08-03 16:27:28 +02:00
|
|
|
|
pip that works out what to install based on your requirements).
|
2020-07-28 16:00:40 +02:00
|
|
|
|
|
|
|
|
|
We're tracking our rollout in :issue:`6536` and you can watch for
|
2020-08-03 16:27:28 +02:00
|
|
|
|
announcements on the `low-traffic packaging announcements list`_ and
|
|
|
|
|
`the official Python blog`_.
|
2020-06-24 06:20:14 +02:00
|
|
|
|
|
2020-03-28 12:15:25 +01:00
|
|
|
|
.. _freeze: https://pip.pypa.io/en/latest/reference/pip_freeze/
|
2020-07-28 15:23:07 +02:00
|
|
|
|
.. _resolver testing survey: https://tools.simplysecure.org/survey/index.php?r=survey/index&sid=989272&lang=en
|
2020-09-30 13:10:09 +02:00
|
|
|
|
.. _issue 8661: https://github.com/pypa/pip/issues/8661
|
2020-07-28 15:23:07 +02:00
|
|
|
|
.. _our announcement on the PSF blog: http://pyfound.blogspot.com/2020/03/new-pip-resolver-to-roll-out-this-year.html
|
|
|
|
|
.. _tensorflow: https://pypi.org/project/tensorflow/
|
2020-07-28 16:00:40 +02:00
|
|
|
|
.. _low-traffic packaging announcements list: https://mail.python.org/mailman3/lists/pypi-announce.python.org/
|
2020-07-28 17:22:57 +02:00
|
|
|
|
.. _our survey on upgrades that create conflicts: https://docs.google.com/forms/d/e/1FAIpQLSeBkbhuIlSofXqCyhi3kGkLmtrpPOEBwr6iJA6SzHdxWKfqdA/viewform
|
2020-08-03 16:27:28 +02:00
|
|
|
|
.. _the official Python blog: https://blog.python.org/
|
2020-08-31 17:27:34 +02:00
|
|
|
|
.. _requests: https://requests.readthedocs.io/en/master/user/authentication/#netrc-authentication
|
|
|
|
|
.. _Python standard library: https://docs.python.org/3/library/netrc.html
|
2020-07-30 09:03:16 +02:00
|
|
|
|
.. _Python Windows launcher: https://docs.python.org/3/using/windows.html#launcher
|