Contents
pip supports installing from PyPI, version control, local projects, and directly from distribution files.
The most common scenario is to install from PyPI using Requirement Specifiers
$ pip install SomePackage # latest version $ pip install SomePackage==1.0.4 # specific version $ pip install 'SomePackage>=1.0.4' # minimum version
For more information and examples, see the pip install reference.
"Requirements files" are files containing a list of items to be installed using pip install like so:
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.
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 freeze was run.
pip freeze > requirements.txt
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 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:
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 ProjectA in your requirements file requires ProjectB, but the latest version (v1.3) has a bug, you can force pip to accept earlier versions like so:
ProjectA
ProjectB<1.3
Requirements files are used to override a dependency with a local patch that lives in version control. For example, suppose a dependency, SomeDependency from 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:
git+https://myvcs.com/some_dependency@sometag#egg=SomeDependency
If SomeDependency was previously a top-level requirement in your requirements file, then replace that line with the new line. If SomeDependency is a sub-dependency, then add the new line.
It's important to be clear that pip determines package dependencies using install_requires metadata, not by discovering requirements.txt files embedded in projects.
See also:
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:
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.
"Wheel" is a built, archive format that can greatly speed installation compared to building and installing from source archives. For more information, see the Wheel docs , PEP427, and PEP425
Pip prefers Wheels where they are available. To disable this, use the --no-binary flag for pip install.
If no satisfactory wheels are found, pip will default to finding source archives.
To install directly from a wheel archive:
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.
pip wheel requires the wheel package to be installed, which provides the "bdist_wheel" setuptools extension that it uses.
To build wheels for your requirements and all their dependencies to a local directory:
pip install wheel
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):
pip install --no-index --find-links=/local/wheels -r requirements.txt
pip is able to uninstall most packages like so:
$ 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:
$ 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:
$ 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:
$ pip show sphinx
---
Name: Sphinx
Version: 1.1.3
Location: /my/env/lib/pythonx.x/site-packages
Requires: Pygments, Jinja2, docutils
For more information and examples, see the pip list and pip show reference pages.
pip can search PyPI for packages using the pip search command:
$ 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 site-wide (shared amongst all users) configuration:
Per-user:
There are also a legacy per-user configuration file which is also respected, these are located at:
You can set a custom path location for this config file using the environment variable PIP_CONFIG_FILE.
Inside a virtualenv:
Site-wide:
If multiple configuration files are found by pip then they are combined in the following order:
Each file read overrides any values read from previous files, so if the global timeout is specified in both the site-wide file and the per-user file then the latter value is the one that 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 = http://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 timeout to 10 seconds when running the freeze (Freezing Requirements) command and using 60 seconds for all other commands is possible with:
[global]
timeout = 60
[freeze]
timeout = 10
Boolean options like --ignore-installed or --no-dependencies can be set like this:
[install]
ignore-installed = true
no-dependencies = yes
To enable the boolean options --no-compile and --no-cache-dir, falsy values have to be used:
[global]
no-cache-dir = false
[install]
no-compile = no
Appending options like --find-links can be written on multiple lines:
[global]
find-links =
http://download.example.com
[install]
find-links =
http://mirror1.example.com
http://mirror2.example.com
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 (_).
For example, to set the default timeout:
export PIP_DEFAULT_TIMEOUT=60
This is the same as passing the option to pip directly:
pip --default-timeout=60 [...]
To set options that can be set multiple times on the command line, just add spaces in between values. For example:
export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
is the same as calling:
pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
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.
Examples:
pip comes with support for command line completion in bash and zsh.
To setup for bash:
$ pip completion --bash >> ~/.profile
To setup for zsh:
$ pip completion --zsh >> ~/.zprofile
Alternatively, you can use the result of the completion command directly with the eval function of you shell, e.g. by adding the following to your startup file:
eval "`pip completion --bash`"
Often, you will want a fast install from local archives, without probing PyPI.
First, download the archives that fulfill your requirements:
$ pip install --download <DIR> -r requirements.txt
Then, install using --find-links and --no-index:
$ pip install --no-index --find-links=[file://]<DIR> -r requirements.txt
pip install --upgrade is currently written to perform an eager recursive upgrade, i.e. it upgrades all dependencies regardless of whether they still satisfy the new parent requirements.
E.g. supposing:
Running pip install --upgrade SomePackage would upgrade SomePackage and AnotherPackage despite AnotherPackage already being satisifed.
pip doesn't currently have an option to do an "only if needed" recursive upgrade, but you can achieve it using these 2 steps:
pip install --upgrade --no-deps SomePackage
pip install SomePackage
The first line will upgrade SomePackage, but not dependencies like AnotherPackage. The 2nd line will fill in new dependencies like OneMorePackage.
See #59 for a plan of making "only if needed" recursive the default behavior for a new pip upgrade command.
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 pip install.
Moreover, the "user scheme" can be customized by setting the PYTHONUSERBASE environment variable, which updates the value of site.USER_BASE.
To install "SomePackage" into an environment with site.USER_BASE customized to '/myappenv', do the following:
export PYTHONUSERBASE=/myappenv
pip install --user SomePackage
pip install --user follows four rules:
To make the rules clearer, here are some examples:
From within a --no-site-packages virtualenv (i.e. the default kind):
$ 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 SomePackage==0.3 is already installed in the virtualenv:
$ 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:
$ pip install --user SomePackage
[...]
Successfully installed SomePackage
From within a real python, where SomePackage is installed globally, but is not the latest version:
$ pip install --user SomePackage
[...]
Requirement already satisfied (use --upgrade to upgrade)
$ pip install --user --upgrade SomePackage
[...]
Successfully installed SomePackage
From within a real python, where SomePackage is installed globally, and is the latest version:
$ pip install --user SomePackage
[...]
Requirement already satisfied (use --upgrade to upgrade)
$ pip install --user --upgrade SomePackage
[...]
Requirement already up-to-date: SomePackage
# force the install
$ pip install --user --ignore-installed SomePackage
[...]
Successfully installed SomePackage
Four things are required to fully guarantee a repeatable installation using requirements files.
You can create a simple bundle that contains all of the dependencies you wish to install using:
$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX)
$ pip wheel -r requirements.txt --wheel-dir=$tempdir
$ cwd=`pwd`
$ (cd "$tempdir"; tar -cjvf "$cwd/bundled.tar.bz2" *)
Once you have a bundle, you can then install it using:
$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX)
$ (cd $tempdir; tar -xvf /path/to/bundled.tar.bz2)
$ pip install --force-reinstall --ignore-installed --upgrade --no-index --no-deps $tempdir/*