Pip config file windows

Contents

• User Guide
  • Installing Packages
  • Requirements Files
  • Constraints Files
  • Installing from Wheels
  • Uninstalling Packages
  • Listing Packages
  • Searching for Packages
  • Configuration
    • Config file
    • Environment Variables
    • Config Precedence
    • Command Completion
  • Installing from local packages
  • «Only if needed» Recursive Upgrade
  • User Installs
  • Ensuring Repeatability
    • Pinned Version Numbers
    • Hash-checking Mode
    • Installation Bundles

Installing Packages¶

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¶

«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. 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:

1. 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
   

2. 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
   

3. 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:

4. 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:

• Requirements File Format
• pip freeze
• «setup.py vs requirements.txt» (an article by Donald Stufft)

Constraints Files¶

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.

Installing from Wheels¶

«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

Uninstalling Packages¶

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.

Listing Packages¶

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.

Searching for Packages¶

pip can search PyPI for packages using the pip search
command:

The query will be used to search the names and summaries of all
packages.

For more information and examples, see the pip search reference.

Configuration¶

[global]
timeout = 60
index-url = http://download.zope.org/ppix

[global]
timeout = 60

[freeze]
timeout = 10

[install]
ignore-installed = true
no-dependencies = yes

[global]
no-cache-dir = false

[install]
no-compile = no

[global]
find-links =
    http://download.example.com

[install]
find-links =
    http://mirror1.example.com
    http://mirror2.example.com

export PIP_DEFAULT_TIMEOUT=60

pip --default-timeout=60 [...]

export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"

pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com

$ pip completion --bash >> ~/.profile

$ pip completion --zsh >> ~/.zprofile

$ pip completion --fish > ~/.config/fish/completions/pip.fish

eval "`pip completion --bash`"

Installing from local packages¶

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:

$ pip install --download DIR -r requirements.txt

Note that pip install --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
this instead:

$ pip wheel --wheel-dir DIR -r requirements.txt

Then, to install from local only, you’ll be using —find-links and —no-index like so:

$ pip install --no-index --find-links=DIR -r requirements.txt

«Only if needed» Recursive Upgrade¶

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:

• SomePackage-1.0 requires AnotherPackage>=1.0
• SomePackage-2.0 requires AnotherPackage>=1.0 and OneMorePackage==1.0
• SomePackage-1.0 and AnotherPackage-1.0 are currently installed
• SomePackage-2.0 and AnotherPackage-2.0 are the latest versions available on PyPI.

Running pip install --upgrade SomePackage would upgrade SomePackage and
AnotherPackage despite AnotherPackage already being satisfied.

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.

User Installs¶

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:

1. When globally installed packages are on the python path, and they conflict
   with the installation requirements, they are ignored, and not
   uninstalled.
2. 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).
3. 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.
4. 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:

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

Ensuring Repeatability¶

pip can achieve various levels of repeatability:

SomePackage == 1.2.3
DependencyOfSomePackage == 4.5.6

FooProject == 1.2 --hash=sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824

$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX)
$ pip wheel -r requirements.txt --wheel-dir=$tempdir
$ cwd=`pwd`
$ (cd "$tempdir"; tar -cjvf "$cwd/bundled.tar.bz2" *)

$ 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/*

Sign up

Appearance settings