Pip install requirements txt windows

Running pip#

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>

py -m pip <pip arguments>

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

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.

Basic Authentication Credentials

This is now covered in Authentication.

netrc Support

This is now covered in Authentication.

Keyring Support

This is now covered in Authentication.

Using a Proxy Server#

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
  scheme://[user:passwd@]proxy.server:port

• using proxy in a Configuration Files

• by setting the standard environment-variables http_proxy, https_proxy
  and no_proxy.

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

Requirements Files#

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

Requirements files can also be served via a URL, e.g.
http://example.com/requirements.txt besides as local files, so that they can
be stored and served in a centralized place.

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 Installs. In
   this case, your requirement file contains a pinned version of everything that
   was installed when pip freeze was run.

   Unix/macOS

   python -m pip freeze > requirements.txt
   python -m pip install -r requirements.txt
   

   Windows

   py -m pip freeze > requirements.txt
   py -m pip install -r requirements.txt
   

2. Requirements files are used to force pip to properly resolve dependencies.
   pip 20.2 and earlier 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 a subset of Requirements Files, with several kinds of syntax
not allowed: constraints must have a name, they cannot be editable, and they
cannot specify extras. In terms of semantics, 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. In Changes to the pip dependency resolver in 20.3 (2020) we did a fairly comprehensive overhaul, removing several
undocumented and unsupported quirks from the previous implementation,
and stripped constraints files down to being purely a way to specify
global (version) limits for packages.

Same as requirements files, constraints files can also be served via a URL,
e.g. http://example.com/constraints.txt, so that your organization can store and
serve them in a centralized place.

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 , PEP 427, and PEP 425.

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:

python -m pip install SomePackage-1.0-py2.py3-none-any.whl

py -m pip install SomePackage-1.0-py2.py3-none-any.whl

To include optional dependencies provided in the provides_extras
metadata in the wheel, you must add quotes around the install target
name:

python -m pip install './somepackage-1.0-py2.py3-none-any.whl[my-extras]'

py -m pip install './somepackage-1.0-py2.py3-none-any.whl[my-extras]'

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:

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

Uninstalling Packages#

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.

Listing Packages#

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

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:

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

Configuration

This is now covered in Configuration.

Config file

This is now covered in Configuration.

Environment Variables

This is now covered in Configuration.

Config Precedence

This is now covered in Configuration.

Command Completion#

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

To setup for powershell:

python -m pip completion --powershell | Out-File -Encoding default -Append $PROFILE

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:

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:

python -m pip download --destination-directory DIR -r requirements.txt

py -m pip download --destination-directory DIR -r requirements.txt

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

python -m pip wheel --wheel-dir DIR -r requirements.txt

py -m 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:

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

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

“Only if needed” Recursive Upgrade#

pip install --upgrade now has a --upgrade-strategy option which
controls how pip handles upgrading of dependencies. There are 2 upgrade
strategies supported:

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

It is important to note that --upgrade affects direct requirements (e.g.
those specified on the command-line or via a requirements file) while
--upgrade-strategy affects indirect requirements (dependencies of direct
requirements).

As an example, say SomePackage has a dependency, SomeDependency, and
both of them are already installed but are not the latest available versions:

• pip install SomePackage: will not upgrade the existing SomePackage or
  SomeDependency.

• pip install --upgrade SomePackage: will upgrade SomePackage, but not
  SomeDependency (unless a minimum requirement is not met).

• pip install --upgrade SomePackage --upgrade-strategy=eager: upgrades both
  SomePackage and SomeDependency.

As an historic note, an earlier “fix” for getting the only-if-needed
behaviour was:

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.

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
python -m pip install --user SomePackage

set PYTHONUSERBASE=c:/myappenv
py -m 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):

$ 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 SomePackage==0.3
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

Ensuring Repeatability

This is now covered in Repeatable Installs.

Fixing conflicting dependencies

This is now covered in Dependency Resolution.

Using pip from your program#

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:

1. The pip code assumes that it 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.

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

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

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 module:

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

• 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).

Changes to the pip dependency resolver in 20.3 (2020)#

pip 20.3 has a new dependency resolver, on by default for Python 3
users. (pip 20.1 and 20.2 included pre-release versions of the new
dependency resolver, hidden behind optional user flags.) Read below
for a migration guide, how to invoke the legacy resolver, and the
deprecation timeline. We also made a two-minute video explanation
you can watch.

We will continue to improve the pip dependency resolver in response to
testers’ feedback. Please give us feedback through the resolver
testing survey.

Usage#

python -m pip install [options] <requirement specifier> [package-index-options] ...
python -m pip install [options] -r <requirements file> [package-index-options] ...
python -m pip install [options] [-e] <vcs project url> ...
python -m pip install [options] [-e] <local project path> ...
python -m pip install [options] <archive url/path> ...

py -m pip install [options] <requirement specifier> [package-index-options] ...
py -m pip install [options] -r <requirements file> [package-index-options] ...
py -m pip install [options] [-e] <vcs project url> ...
py -m pip install [options] [-e] <local project path> ...
py -m pip install [options] <archive url/path> ...

Description#

Install packages from:

• PyPI (and other indexes) using requirement specifiers.

• VCS project urls.

• Local project directories.

• Local or remote source archives.

pip also supports installing from “requirements files”, which provide
an easy way to specify a whole environment to be installed.

$ python -m pip install quux
...
Installing collected packages baz, bar, foo, quux

$ python -m pip install bar
...
Installing collected packages foo, baz, bar

C:\> py -m pip install quux
...
Installing collected packages baz, bar, foo, quux

C:\> py -m pip install bar
...
Installing collected packages foo, baz, bar

Options#

-r, —requirement <file>#

Install from the given requirements file. This option can be used multiple times.

-c, —constraint <file>#

Constrain versions using the given constraints file. This option can be used multiple times.

—no-deps#

Don’t install package dependencies.

—pre#

Include pre-release and development versions. By default, pip only finds stable versions.

-e, —editable <path/url>#

Install a project in editable mode (i.e. setuptools “develop mode”) from a local project path or a VCS url.

—dry-run#

Don’t actually install anything, just print what would be. Can be used in combination with —ignore-installed to ‘resolve’ the requirements.

-t, —target <dir>#

Install packages into <dir>. By default this will not replace existing files/folders in <dir>. Use —upgrade to replace existing packages in <dir> with new versions.

—platform <platform>#

Only use wheels compatible with <platform>. Defaults to the platform of the running system. Use this option multiple times to specify multiple platforms supported by the target interpreter.

—python-version <python_version>#

The Python interpreter version to use for wheel and “Requires-Python”
compatibility checks. Defaults to a version derived from the running
interpreter. The version can be specified using up to three dot-separated
integers (e.g. “3” for 3.0.0, “3.7” for 3.7.0, or “3.7.3”). A major-minor
version can also be given as a string without dots (e.g. “37” for 3.7.0).

—implementation <implementation>#

Only use wheels compatible with Python implementation <implementation>, e.g. ‘pp’, ‘jy’, ‘cp’, or ‘ip’. If not specified, then the current interpreter implementation is used. Use ‘py’ to force implementation-agnostic wheels.

—abi <abi>#

Only use wheels compatible with Python abi <abi>, e.g. ‘pypy_41’. If not specified, then the current interpreter abi tag is used. Use this option multiple times to specify multiple abis supported by the target interpreter. Generally you will need to specify —implementation, —platform, and —python-version when using this option.

—user#

Install to the Python user install directory for your platform. Typically ~/.local/, or %APPDATA%Python on Windows. (See the Python documentation for site.USER_BASE for full details.)

—root <dir>#

Install everything relative to this alternate root directory.

—prefix <dir>#

Installation prefix where lib, bin and other top-level folders are placed. Note that the resulting installation may contain scripts and other resources which reference the Python interpreter of pip, and not that of --prefix. See also the --python option if the intention is to install packages into another (possibly pip-free) environment.

—src <dir>#

Directory to check out editable projects into. The default in a virtualenv is “<venv path>/src”. The default for global installs is “<current dir>/src”.

-U, —upgrade#

Upgrade all specified packages to the newest available version. The handling of dependencies depends on the upgrade-strategy used.

—upgrade-strategy <upgrade_strategy>#

Determines how dependency upgrading should be handled [default: only-if-needed]. “eager” — dependencies are upgraded regardless of whether the currently installed version satisfies the requirements of the upgraded package(s). “only-if-needed” — are upgraded only when they do not satisfy the requirements of the upgraded package(s).

—force-reinstall#

Reinstall all packages even if they are already up-to-date.

-I, —ignore-installed#

Ignore the installed packages, overwriting them. This can break your system if the existing package is of a different version or was installed with a different package manager!

—ignore-requires-python#

Ignore the Requires-Python information.

—no-build-isolation#

Disable isolation when building a modern source distribution. Build dependencies specified by PEP 518 must be already installed if this option is used.

—use-pep517#

Use PEP 517 for building source distributions (use —no-use-pep517 to force legacy behaviour).

—check-build-dependencies#

Check the build dependencies when PEP517 is used.

—break-system-packages#

Allow pip to modify an EXTERNALLY-MANAGED Python installation

-C, —config-settings <settings>#

Configuration settings to be passed to the PEP 517 build backend. Settings take the form KEY=VALUE. Use multiple —config-settings options to pass multiple keys to the backend.

—global-option <options>#

Extra global options to be supplied to the setup.py call before the install or bdist_wheel command.

—compile#

Compile Python source files to bytecode

—no-compile#

Do not compile Python source files to bytecode

—no-warn-script-location#

Do not warn when installing scripts outside PATH

—no-warn-conflicts#

Do not warn about broken dependencies

—no-binary <format_control>#

Do not use binary packages. Can be supplied multiple times, and each time adds to the existing value. Accepts either “:all:” to disable all binary packages, “:none:” to empty the set (notice the colons), or one or more package names with commas between them (no colons). Note that some packages are tricky to compile and may fail to install when this option is used on them.

—only-binary <format_control>#

Do not use source packages. Can be supplied multiple times, and each time adds to the existing value. Accepts either “:all:” to disable all source packages, “:none:” to empty the set, or one or more package names with commas between them. Packages without binary distributions will fail to install when this option is used on them.

—prefer-binary#

Prefer older binary packages over newer source packages.

—require-hashes#

Require a hash to check each requirement against, for repeatable installs. This option is implied when any package in a requirements file has a —hash option.

—progress-bar <progress_bar>#

Specify whether the progress bar should be used [on, off] (default: on)

—root-user-action <root_user_action>#

Action if pip is run as a root user. By default, a warning message is shown.

—report <file>#

Generate a JSON file describing what pip did to install the provided requirements. Can be used in combination with —dry-run and —ignore-installed to ‘resolve’ the requirements. When — is used as file name it writes to stdout. When writing to stdout, please combine with the —quiet option to avoid mixing pip logging output with JSON output.

—no-clean#

Don’t clean up build directories.

-i, —index-url <url>#

Base URL of the Python Package Index (default https://pypi.org/simple). This should point to a repository compliant with PEP 503 (the simple repository API) or a local directory laid out in the same format.

Extra URLs of package indexes to use in addition to —index-url. Should follow the same rules as —index-url.

—no-index#

Ignore package index (only looking at —find-links URLs instead).

-f, —find-links <url>#

If a URL or path to an html file, then parse for links to archives such as sdist (.tar.gz) or wheel (.whl) files. If a local path or file:// URL that’s a directory, then look for archives in the directory listing. Links to VCS project URLs are not supported.

Examples#

1. Install SomePackage and its dependencies from PyPI using Requirement Specifiers

   Unix/macOS

   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
   

   Windows

   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
   

2. Install a list of requirements specified in a file. See the Requirements files.

   Unix/macOS

   python -m pip install -r requirements.txt
   

   Windows

   py -m pip install -r requirements.txt
   

3. Upgrade an already installed SomePackage to the latest from PyPI.

   Unix/macOS

   python -m pip install --upgrade SomePackage
   

   Windows

   py -m pip install --upgrade SomePackage
   

   Note

   This will guarantee an update to SomePackage as it is a direct
   requirement, and possibly upgrade dependencies if their installed
   versions do not meet the minimum requirements of SomePackage.
   Any non-requisite updates of its dependencies (indirect requirements)
   will be affected by the --upgrade-strategy command.

4. Install a local project in “editable” mode. See the section on Editable Installs.

   Unix/macOS

   python -m pip install -e .                # project in current directory
   python -m pip install -e path/to/project  # project in another directory
   

   Windows

   py -m pip install -e .                 # project in current directory
   py -m pip install -e path/to/project   # project in another directory
   

5. Install a project from VCS

   Unix/macOS

   python -m pip install 'SomeProject@git+https://git.repo/some_pkg.git@1.3.1'
   

   Windows

   py -m pip install "SomeProject@git+https://git.repo/some_pkg.git@1.3.1"
   

6. Install a project from VCS in “editable” mode. See the sections on VCS Support and Editable Installs.

   Unix/macOS

   python -m pip install -e 'git+https://git.repo/some_pkg.git#egg=SomePackage'          # from git
   python -m pip install -e 'hg+https://hg.repo/some_pkg.git#egg=SomePackage'            # from mercurial
   python -m pip install -e 'svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage'         # from svn
   python -m pip install -e 'git+https://git.repo/some_pkg.git@feature#egg=SomePackage'  # from 'feature' branch
   python -m pip install -e 'git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path' # install a python package from a repo subdirectory
   

   Windows

   py -m pip install -e "git+https://git.repo/some_pkg.git#egg=SomePackage"          # from git
   py -m pip install -e "hg+https://hg.repo/some_pkg.git#egg=SomePackage"            # from mercurial
   py -m pip install -e "svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage"         # from svn
   py -m pip install -e "git+https://git.repo/some_pkg.git@feature#egg=SomePackage"  # from 'feature' branch
   py -m pip install -e "git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path" # install a python package from a repo subdirectory
   

7. Install a package with extras.

   Unix/macOS

   python -m pip install 'SomePackage[PDF]'
   python -m pip install 'SomePackage[PDF] @ git+https://git.repo/SomePackage@main#subdirectory=subdir_path'
   python -m pip install '.[PDF]'  # project in current directory
   python -m pip install 'SomePackage[PDF]==3.0'
   python -m pip install 'SomePackage[PDF,EPUB]'  # multiple extras
   

   Windows

   py -m pip install "SomePackage[PDF]"
   py -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@main#subdirectory=subdir_path"
   py -m pip install ".[PDF]"  # project in current directory
   py -m pip install "SomePackage[PDF]==3.0"
   py -m pip install "SomePackage[PDF,EPUB]"  # multiple extras
   

8. Install a particular source archive file.

   Unix/macOS

   python -m pip install './downloads/SomePackage-1.0.4.tar.gz'
   python -m pip install 'http://my.package.repo/SomePackage-1.0.4.zip'
   

   Windows

   py -m pip install "./downloads/SomePackage-1.0.4.tar.gz"
   py -m pip install "http://my.package.repo/SomePackage-1.0.4.zip"
   

9. Install a particular source archive file following PEP 440 direct references.

   Unix/macOS

   python -m pip install 'SomeProject@http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl'
   python -m pip install 'SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl'
   python -m pip install 'SomeProject@http://my.package.repo/1.2.3.tar.gz'
   

   Windows

   py -m pip install "SomeProject@http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl"
   py -m pip install "SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl"
   py -m pip install "SomeProject@http://my.package.repo/1.2.3.tar.gz"
   

10. Install from alternative package repositories.

    Install from a different index, and not PyPI

    Unix/macOS

    python -m pip install --index-url http://my.package.repo/simple/ SomePackage
    

    Windows

    py -m pip install --index-url http://my.package.repo/simple/ SomePackage
    

    Install from a local flat directory containing archives (and don’t scan indexes):

    Unix/macOS

    python -m pip install --no-index --find-links=file:///local/dir/ SomePackage
    python -m pip install --no-index --find-links=/local/dir/ SomePackage
    python -m pip install --no-index --find-links=relative/dir/ SomePackage
    

    Windows

    py -m pip install --no-index --find-links=file:///local/dir/ SomePackage
    py -m pip install --no-index --find-links=/local/dir/ SomePackage
    py -m pip install --no-index --find-links=relative/dir/ SomePackage
    

    Search an additional index during install, in addition to PyPI

    Warning

    Using this option to search for packages which are not in the main
    repository (such as private packages) is unsafe, per a security
    vulnerability called
    dependency confusion:
    an attacker can claim the package on the public repository in a way that
    will ensure it gets chosen over the private package.

    Unix/macOS

    python -m pip install --extra-index-url http://my.package.repo/simple SomePackage
    

    Windows

    py -m pip install --extra-index-url http://my.package.repo/simple SomePackage
    

11. Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions.

    Unix/macOS

    python -m pip install --pre SomePackage
    

    Windows

    py -m pip install --pre SomePackage
    

12. Install packages from source.

    Do not use any binary packages

    Unix/macOS

    python -m pip install SomePackage1 SomePackage2 --no-binary :all:
    

    Windows

    py -m pip install SomePackage1 SomePackage2 --no-binary :all:
    

    Specify SomePackage1 to be installed from source:

    Unix/macOS

    python -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1
    

    Windows

    py -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1