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 freeze was run.

pipfreeze>requirements.txtpipinstall-rrequirements.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:

pkg1pkg2pkg3>=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:

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

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:

pipinstall-cconstraints.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.

On macOS the configuration file is
$HOME/Library/ApplicationSupport/pip/pip.conf
if directory $HOME/Library/ApplicationSupport/pip exists
else $HOME/.config/pip/pip.conf.

On Windows the configuration file is %APPDATA%\pip\pip.ini.

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: $HOME/.pip/pip.conf

On Windows the configuration file is: %HOME%\pip\pip.ini

You can set a custom path location for this config file using the environment
variable PIP_CONFIG_FILE.

Inside a virtualenv:

On Unix and macOS the file is $VIRTUAL_ENV/pip.conf

On Windows the file is: %VIRTUAL_ENV%\pip.ini

Site-wide:

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
/etc/xdg/pip/pip.conf.

On Windows 7 and later the file is hidden, but writeable at
C:\ProgramData\pip\pip.ini

Site-wide configuration is not supported on Windows Vista

If multiple configuration files are found by pip then they are combined in
the following order:

The site-wide 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 site-wide 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=60index-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
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=trueno-dependencies=yes

To enable the boolean options --no-compile and --no-cache-dir, falsy
values have to be used:

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

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

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:

exportPYTHONUSERBASE=/myappenvpipinstall--userSomePackage

pipinstall--user follows four rules:

When globally installed packages are on the python path, and they conflict
with the installation requirements, they are ignored, and not
uninstalled.

When globally installed packages are on the python path, and they satisfy
the installation requirements, pip does nothing, and reports that
requirement is satisfied (similar to how global packages can satisfy
requirements when installing packages in a --system-site-packages
virtualenv).

pip will not perform a --user install in a --no-site-packages
virtualenv (i.e. the default kind of virtualenv), due to the user site not
being on the python path. The installation would be pointless.

In a --system-site-packages virtualenv, pip will not install a package
that conflicts with a package in the virtualenv site-packages. The –user
installation would lack sys.path precedence and be pointless.

To make the rules clearer, here are some examples:

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:

Pinning the versions of your dependencies in the requirements file
protects you from bugs or incompatibilities in newly released versions:

SomePackage==1.2.3DependencyOfSomePackage==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.)

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.

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:

Note that compiled packages are typically OS- and architecture-specific, so
these archives are not necessarily portable across machines.

Hash-checking mode can be used along with this method to ensure that future
archives are built with identical packages.

Warning

Finally, beware of the setup_requires keyword arg in setup.py.
The (rare) packages that use it will cause those dependencies to be
downloaded by setuptools directly, skipping pip’s protections. If you need
to use such a package, see Controlling
setup_requires.

As noted previously, pip is a command line program. While it is implemented in Python,
and so is available from your Python code via importpip, 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 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:

If you want to process the output further, use one of the other APIs in the module:

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: