pip is a command line program. When you install pip, a
pip command is added
to your system, which can be run from the command prompt as follows:
python -m pip <pip arguments>
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.
py -m pip <pip arguments>
py -m pip executes pip using the latest Python interpreter you
have installed. For more details, read the Python Windows launcher docs.
pip supports installing from PyPI, version control, local projects, and directly from distribution files.
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
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
For more information and examples, see the pip install reference.
pip supports basic authentication credentials. Basically, in the URL there is
a username and password separated by
Certain special characters are not valid in the authentication part of URLs. If the user or password part of your login credentials contain any of the special characters here then they must be percent-encoded. For example, for a user with username “user” and password “he//o” accessing a repository at pypi.company.com, the index URL with credentials would look like:
Support for percent-encoded authentication in index URLs was added in pip 10.0.0 (in #3236). Users that must use authentication 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.
For indexes that only require single-part authentication tokens, provide the token as the “username” and do not provide a password, for example -
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:
machine example.com login daniel password qwerty
As mentioned in the standard library docs, only ASCII characters are allowed. Whitespace and non-printable characters are not allowed in passwords.
pip also supports credentials stored in your keyring using the keyring
library. Note that
keyring will need to be installed separately, as pip
does not come with it included.
pip install keyring echo your-password | keyring set pypi.company.com your-username pip install your-package --extra-index-url https://pypi.company.com/
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:
--proxycommand-line option to specify a proxy in the form
proxyin a Config file
by setting the standard environment-variables
using the environment variable
PIP_USER_AGENT_USER_DATAto include a JSON-encoded string in the user-agent variable used in pip’s requests.
“Requirements files” are files containing a list of items to be installed using pip install like so:
python -m pip install -r requirements.txt
py -m pip install -r requirements.txt
Details on the format of the files are here: Requirements File Format.
Logically, a Requirements file is just a list of pip install arguments placed in a file. Note that you should not rely on the items in the file being installed by pip in any particular order.
In practice, there are 4 common uses of Requirements files:
Requirements files are used to hold the result from pip freeze for the purpose of achieving repeatable installations. In this case, your requirement file contains a pinned version of everything that was installed when
pip freezewas run.
python -m pip freeze > requirements.txt python -m pip install -r requirements.txt
py -m pip freeze > requirements.txt py -m pip install -r requirements.txt
Requirements files are used to force pip to properly resolve dependencies. As it is now, pip doesn’t have true dependency resolution, but instead simply uses the first specification it finds for a project. E.g. if
pkg3>=1.0,<=2.0, and if
pkg1is resolved first, pip will only use
pkg3>=1.0, and could easily end up installing a version of
pkg3that 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:
pkg1 pkg2 pkg3>=1.0,<=2.0
Requirements files are used to force pip to install an alternate version of a sub-dependency. For example, suppose
ProjectAin your requirements file requires
ProjectB, but the latest version (v1.3) has a bug, you can force pip to accept earlier versions like so:
Requirements files are used to override a dependency with a local patch that lives in version control. For example, suppose a dependency
SomeDependencyfrom PyPI has a bug, and you can’t wait for an upstream fix. You could clone/copy the src, make the fix, and place it in VCS with the tag
sometag. You’d reference it in your requirements file with a line like so:
SomeDependencywas previously a top-level requirement in your requirements file, then replace that line with the new line. If
SomeDependencyis a sub-dependency, then add the new line.
It’s important to be clear that pip determines package dependencies using
not by discovering
requirements.txt files embedded in projects.
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 Requirements Files. There is one key difference: Including a package in a constraints file does not trigger installation of the package.
Use a constraints file like so:
python -m pip install -c constraints.txt
py -m pip install -c constraints.txt
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.
If no satisfactory wheels are found, pip will default to finding source archives.
To install directly from a wheel archive:
python -m pip install SomePackage-1.0-py2.py3-none-any.whl
py -m pip install SomePackage-1.0-py2.py3-none-any.whl
For the cases where wheels are not available, pip offers pip wheel as a convenience, to build wheels for all your requirements and dependencies.
To build wheels for your requirements and all their dependencies to a local directory:
python -m pip install wheel python -m pip wheel --wheel-dir=/local/wheels -r requirements.txt
py -m pip install wheel py -m pip wheel --wheel-dir=/local/wheels -r requirements.txt
And then to install those requirements just using your local directory of wheels (and not from PyPI):
python -m pip install --no-index --find-links=/local/wheels -r requirements.txt
py -m pip install --no-index --find-links=/local/wheels -r requirements.txt
pip is able to uninstall most packages like so:
python -m pip uninstall SomePackage
py -m pip uninstall SomePackage
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 pip uninstall reference.
To list installed packages:
$ python -m pip list docutils (0.9.1) Jinja2 (2.6) Pygments (1.5) Sphinx (1.1.2)
C:\> py -m pip list docutils (0.9.1) Jinja2 (2.6) Pygments (1.5) Sphinx (1.1.2)
To list outdated packages, and show the latest version available:
$ python -m pip list --outdated docutils (Current: 0.9.1 Latest: 0.10) Sphinx (Current: 1.1.2 Latest: 1.1.3)
C:\> py -m pip list --outdated docutils (Current: 0.9.1 Latest: 0.10) Sphinx (Current: 1.1.2 Latest: 1.1.3)
To show details about an installed package:
$ python -m pip show sphinx --- Name: Sphinx Version: 1.1.3 Location: /my/env/lib/pythonx.x/site-packages Requires: Pygments, Jinja2, docutils
C:\> py -m pip show sphinx --- Name: Sphinx Version: 1.1.3 Location: /my/env/lib/pythonx.x/site-packages Requires: Pygments, Jinja2, docutils
pip can search PyPI for packages using the
python -m pip search "query"
py -m pip search "query"
The query will be used to search the names and summaries of all packages.
For more information and examples, see the pip search reference.
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 platforms. You may have per-user, per-virtualenv or global (shared amongst all users) configuration:
On Unix the default configuration file is:
$HOME/.config/pip/pip.confwhich respects the
On macOS the configuration file is
$HOME/Library/Application Support/pip/pip.confif directory
$HOME/Library/Application Support/pipexists else
On Windows the configuration file is
There are also a legacy per-user configuration file which is also respected, these are located at:
On Unix and macOS the configuration file is:
On Windows the configuration file is:
You can set a custom path location for this config file using the environment
Inside a virtualenv:
On Unix and macOS the file is
On Windows the file is:
On Unix the file may be located in
/etc/pip.conf. Alternatively 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
On macOS the file is:
On Windows XP the file is:
C:\Documents and Settings\All Users\Application Data\pip\pip.ini
On Windows 7 and later the file is hidden, but writeable at
Global configuration is not supported on Windows Vista.
The global configuration file is shared by all Python installations.
If multiple configuration files are found by pip then they are combined in the following order:
The global file is read
The per-user file is read
The virtualenv-specific file is read
Each file read overrides any values read from previous files, so if the global timeout is specified in both the global file and the per-user file then the latter value will be used.
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:
[global] timeout = 60 index-url = https://download.zope.org/ppix
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
10 seconds when running the
(pip freeze) command and using
60 seconds for all other commands is possible with:
[global] timeout = 60 [freeze] timeout = 10
Boolean options like
--no-dependencies can be
set like this:
[install] ignore-installed = true no-dependencies = yes
To enable the boolean options
--no-cache-dir, falsy values have to be used:
[global] no-cache-dir = false [install] no-compile = no no-warn-script-location = false
For options which can be repeated like
a non-negative integer can be used to represent the level to be specified:
[global] quiet = 0 verbose = 2
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
which can be written on multiple lines:
[global] find-links = http://download.example.com [install] find-links = http://mirror1.example.com http://mirror2.example.com 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.
pip’s command line options can be set with environment variables using the
PIP_<UPPER_LONG_NAME> . Dashes (
-) have to be replaced with
For example, to set the default timeout:
This is the same as passing the option to pip directly:
python -m pip --default-timeout=60 [...]
py -m pip --default-timeout=60 [...]
For command line options which can be repeated, use a space to separate multiple values. For example:
export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
set PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
is the same as calling:
python -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
py -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
Options that do not take a value, but can be repeated (such as
can be specified using the number of repetitions, so:
is the same as calling:
pip install -vvv
Environment variables set to be empty string will not be treated as false.
Command line options have precedence over environment variables, which have precedence over the config file.
Within the config file, command specific sections have precedence over the global section.
PIP_HOST=foooverrides a config file with
[global] host = foo
A command specific section in the config file
[<command>] host = baroverrides the option with same name in the
[global]config file section
pip comes with support for command line completion in bash, zsh and fish.
To setup for bash:
python -m pip completion --bash >> ~/.profile
To setup for zsh:
python -m pip completion --zsh >> ~/.zprofile
To setup for fish:
python -m pip completion --fish > ~/.config/fish/completions/pip.fish
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
eval "`pip completion --bash`"
In some cases, you may want to install from local packages only, with no traffic to PyPI.
First, download the archives that fulfill your requirements:
python -m pip download --destination-directory DIR -r requirements.txt
py -m pip download --destination-directory DIR -r requirements.txt
pip download will look in your wheel cache first, before
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
python -m pip wheel --wheel-dir DIR -r requirements.txt
py -m pip wheel --wheel-dir DIR -r requirements.txt
python -m pip install --no-index --find-links=DIR -r requirements.txt
py -m pip install --no-index --find-links=DIR -r requirements.txt
pip install --upgrade now has a
--upgrade-strategy option which
controls how pip handles upgrading of dependencies. There are 2 upgrade
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
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.
As an historic note, an earlier “fix” for getting the
python -m pip install --upgrade --no-deps SomePackage python -m pip install SomePackage
py -m pip install --upgrade --no-deps SomePackage py -m pip install SomePackage
A proposal for an
upgrade-all command is being considered as a safer
alternative to the behaviour of eager upgrading.
With Python 2.6 came the “user scheme” for installation,
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 variable.
This mode of installation can be turned on by specifying the --user option to
Moreover, the “user scheme” can be customized by setting the
PYTHONUSERBASE environment variable, which updates the value of
To install “SomePackage” into an environment with site.USER_BASE customized to ‘/myappenv’, do the following:
export PYTHONUSERBASE=/myappenv python -m pip install --user SomePackage
set PYTHONUSERBASE=c:/myappenv py -m pip install --user SomePackage
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
pip will not perform a
--userinstall in a
--no-site-packagesvirtualenv (i.e. the default kind of virtualenv), due to the user site not being on the python path. The installation would be pointless.
--system-site-packagesvirtualenv, 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:
From within a
--no-site-packages virtualenv (i.e. the default kind):
$ python -m pip install --user SomePackage Can not perform a '--user' install. User site-packages are not visible in this virtualenv.
C:\> py -m pip install --user SomePackage Can not perform a '--user' install. User site-packages are not visible in this virtualenv.
From within a
--system-site-packages virtualenv where
is already installed in the virtualenv:
$ python -m pip install --user SomePackage==0.4 Will not install to the user site because it will lack sys.path precedence
C:\> py -m pip install --user SomePackage==0.4 Will not install to the user site because it will lack sys.path precedence
From within a real python, where
SomePackage is not installed globally:
$ python -m pip install --user SomePackage [...] Successfully installed SomePackage
C:\> py -m pip install --user SomePackage [...] Successfully installed SomePackage
From within a real python, where
SomePackage is installed globally, but
is not the latest version:
$ python -m pip install --user SomePackage [...] Requirement already satisfied (use --upgrade to upgrade) $ python -m pip install --user --upgrade SomePackage [...] Successfully installed SomePackage
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
From within a real python, where
SomePackage is installed globally, and
is the latest version:
$ 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
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
pip can achieve various levels of repeatability:
Pinning the versions of your dependencies in the requirements file protects you from bugs or incompatibilities in newly released versions:
SomePackage == 1.2.3 DependencyOfSomePackage == 4.5.6
Using 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 --no-deps for an extra dose of insurance against installing anything not explicitly listed.
This strategy is easy to implement and works across OSes and architectures. 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.)
Beyond pinning version numbers, you can add hashes against which to verify downloaded packages:
FooProject == 1.2 --hash=sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
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.
Hash-checking mode is a labor-saving alternative to running a private index server containing approved packages: it removes the need to upload packages, maintain ACLs, and keep an audit trail (which a VCS gives you on the requirements file for free). It can also substitute for a vendor library, providing easier upgrades and less VCS noise. It does not, of course, provide the availability benefits of a private index or a vendor library.
For more, see pip install’s discussion of hash-checking mode.
Using 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:
$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX) $ python -m pip wheel -r requirements.txt --wheel-dir=$tempdir $ cwd=`pwd` $ (cd "$tempdir"; tar -cjvf "$cwd/bundled.tar.bz2" *)
You can then install from the archive like this:
$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX) $ (cd $tempdir; tar -xvf /path/to/bundled.tar.bz2) $ python -m pip install --force-reinstall --ignore-installed --upgrade --no-index --no-deps $tempdir/*
Note that compiled packages are typically OS- and architecture-specific, so these archives are not necessarily portable across macOShines.
Hash-checking mode can be used along with this method to ensure that future archives are built with identical packages.
Finally, beware of the
setup_requires keyword arg in
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 Controlling
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
This documentation is specific to the new resolver, which you can use
with the flag
When you get a
ResolutionImpossible error, you might see something
python -m pip install package_coffee==0.44.1 package_tea==4.3.0
py -m pip install package_coffee==0.44.1 package_tea==4.3.0
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
In this example, pip cannot install the packages you have requested,
because they each depend on different versions of the same package
0.44.1depends on a version of
package_waterthat is less than
3.0.0but greater than or equal to
4.3.0depends on version
Sometimes these messages are straightforward to read, because they use
commonly understood comparison operators to specify the required version
However, Python packaging also supports some more complex ways for
specifying package versions (e.g.
Any version greater than the specified version.
Any version less than the specified version.
Any version less than or equal to the specified version.
Any version greater than or equal to the specified version.
Exactly the specified version.
Any version not equal to the specified version.
Any compatible release. Compatible releases are releases that are within the same major or minor version, assuming the package author is using semantic versioning.
Can be used at the end of a version number to represent all,
The detailed specification of supported comparison operators can be found in PEP 440.
The solution to your error will depend on your individual use case. Here are some things to try:
As a first step it is useful to audit your project and remove any
unnecessary or out of date requirements (e.g. from your
requirements.txt files). Removing these can significantly reduce the
complexity of your dependency tree, thereby reducing opportunities for
conflicts to occur.
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_tea have been
pinned to use specific versions
To find a version of both
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_teaby removing the version specifiers altogether (e.g.
python -m pip install package_coffee package_tea)
In the second case, pip will automatically find a version of both
package_tea that depend on the same version of
package_coffee 0.46.0b0, which depends on
package_tea 4.3.0which also depends on
If you want to prioritize one package over another, you can add version specifiers to only the more important package:
python -m pip install package_coffee==0.44.1b0 package_tea
py -m pip install package_coffee==0.44.1b0 package_tea
This will result in:
package_coffee 0.44.1b0, which depends on
package_tea 4.1.3which also depends on
Now that you have resolved the issue, you can repin the compatible package versions as required.
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
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!
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)
If none of the suggestions above work for you, we recommend that you ask for help on:
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.
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:
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.
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.
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.
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.
What this means in practice is that everything inside of pip is considered an
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
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.
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
approach, and the one that is fully supported, is to run pip in a subprocess.
This is easily done using the standard
subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'my_package'])
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.:
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.)
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).
pip 20.1 included an alpha version of the new resolver (hidden behind
--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.
The big change in this release is to the pip dependency resolver within pip.
Computers need to know the right order to install pieces of software
x, you need to install
y first”). So, when Python
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
logic, and make pip easier for you to use and troubleshoot.
The most significant changes to the resolver are:
It will reduce inconsistency: it will no longer install a 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
six>=1.12.0,<2(defined here). The new resolver, instead, outright rejects installing anything if it gets that input.
It will be stricter - if you ask pip to install two packages with incompatible requirements, it will refuse (rather than installing a broken combination, like it did in previous versions).
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.
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
pip install y, it’s possible that the version of
you get will be different than it would be if you had run
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
We are also changing our support for Constraints Files:
Install pip 20.2 with
python -m pip install --upgrade pip.
Validate your current environment by running
pip check. This 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 checkand run into stuff you can’t figure out, please ask for help in our issue tracker or chat.
Test the new version of pip (see below). To test the new resolver, use the
--use-feature=2020-resolverflag, 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.
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:
installing several packages simultaneously
re-creating an environment using a
pip install --force-reinstallto check whether it does what you think it should
using constraints files
If you have a build pipeline that depends on pip installing your dependencies for you, check that the new resolver does what you need.
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_FEATUREenvironment variable option, see issue 8661).
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 with pip 20.2.
Please report bugs through the resolver testing survey.
Windows, including Windows Subsystem for Linux (WSL)
Debian, Fedora, Red Hat, CentOS, Mint, Arch, Raspbian, Gentoo
non-Latin localized filesystems and OSes, such as Japanese, Chinese, and Korean, and right-to-left such as Hebrew, Urdu, and Arabic
Requirements files with 100+ packages
An installation workflow that involves multiple requirements files
Requirements files that include hashes (Hash-Checking Mode) or pinned dependencies (perhaps as output from
Using Constraints Files
Continuous integration/continuous deployment setups
Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per VCS Support
Installing from source code held in local directories
Using the most recent versions of Python 3.6, 3.7, 3.8, and 3.9
Customized terminals (where you have modified how error messages and standard output display)
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
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!
Please let us know through the resolver testing survey.
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
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 Deprecation Policy.
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 pip that works out what to install based on your requirements).
Did this article help?
We are currently doing research to improve pip’s documentation and would love your feedback. Please email us and let us know:
What problem were you trying to solve when you came to this page?
What content was useful?
What content was not useful?