pip offers -v, –verbose and -q, –quiet
to control the console log level. By default, some messages (error and warnings)
are colored in the terminal. If you want to suppress the colored output use
–no-color.

This option specifies default behavior when path already exists.
Possible cases: downloading files or checking out repositories for installation,
creating archives. If --exists-action is not defined, pip will prompt
when decision is needed.

(s)witch

Only relevant to VCS checkout. Attempt to switch the checkout
to the appropriate url and/or revision.

Delete the file or VCS checkout before trying to create, download, or checkout a new one.

(b)ackup

Rename the file or checkout to {name}{'.bak'*n}, where n is some number
of .bak extensions, such that the file didn’t exist at some point.
So the most recent backup will be the one with the largest number after .bak.

Pip builds packages by invoking the build system. By default, builds will use
setuptools, but if a project specifies a different build system using a
pyproject.toml file, as per PEP 517, pip will use that instead. As well
as package building, the build system is also invoked to install packages
direct from source. This is handled by invoking the build system to build a
wheel, and then installing from that wheel. The built wheel is cached locally
by pip to avoid repeated identical builds.

The current interface to the build system is via the setup.py command line
script - all build actions are defined in terms of the specific setup.py
command line that will be run to invoke the required action.

When PEP 517 is not used, the supported build system is setuptools.
However, not all packages use setuptools in their build scripts. To support
projects that use “pure distutils”, pip injects setuptools into
sys.modules before invoking setup.py. The injection should be
transparent to distutils-based projects, but 3rd party build tools wishing
to provide a setup.py emulating the commands pip requires may need to be
aware that it takes place.

Projects using PEP 517must explicitly use setuptools - pip does not do
the above injection process in this case.

Any output produced by the build system will be read by pip (for display to the
user if requested). In order to correctly read the build system output, pip
requires that the output is written in a well-defined encoding, specifically
the encoding the user has configured for text output (which can be obtained in
Python using locale.getpreferredencoding). If the configured encoding is
ASCII, pip assumes UTF-8 (to account for the behaviour of some Unix systems).

Build systems should ensure that any tools they invoke (compilers, etc) produce
output in the correct encoding. In practice - and in particular on Windows,
where tools are inconsistent in their use of the “OEM” and “ANSI” codepages -
this may not always be possible. Pip will therefore attempt to recover cleanly
if presented with incorrectly encoded build tool output, by translating
unexpected byte sequences to Python-style hexadecimal escape sequences
("\x80\xff", etc). However, it is still possible for output to be displayed
using an incorrect encoding (mojibake).

Under PEP 517, handling of build tool output is the backend’s responsibility,
and pip simply displays the output produced by the backend. (Backends, however,
will likely still have to address the issues described above).

As of version 10.0, pip supports projects declaring dependencies that are
required at install time using a pyproject.toml file, in the form described
in PEP 518. When building a project, pip will install the required
dependencies locally, and make them available to the build process.
Furthermore, from version 19.0 onwards, pip supports projects specifying the
build backend they use in pyproject.toml, in the form described in
PEP 517.

When making build requirements available, pip does so in an isolated
environment. That is, pip does not install those requirements into the user’s
site-packages, but rather installs them in a temporary directory which it
adds to the user’s sys.path for the duration of the build. This ensures
that build requirements are handled independently of the user’s runtime
environment. For example, a project that needs a recent version of setuptools
to build can still be installed, even if the user has an older version
installed (and without silently replacing that version).

In certain cases, projects (or redistributors) may have workflows that
explicitly manage the build environment. For such workflows, build isolation
can be problematic. If this is the case, pip provides a
--no-build-isolation flag to disable build isolation. Users supplying this
flag are responsible for ensuring the build environment is managed
appropriately.

By default, pip will continue to use the legacy (setuptools based) build
processing for projects that do not have a pyproject.toml file. Projects
with a pyproject.toml file will use a PEP 517 backend. Projects with
a pyproject.toml file, but which don’t have a build-system section,
will be assumed to have the following backend settings:

setuptools 40.2.0 is the first version of setuptools with full
PEP 517 support.

If a project has [build-system], but no build-backend, pip will use
setuptools.build_meta, but will assume the project requirements include
setuptools>=40.2.0 and wheel (and will report an error if not).

If a user wants to explicitly request PEP 517 handling even though a project
doesn’t have a pyproject.toml file, this can be done using the
--use-pep517 command line option. Similarly, to request legacy processing
even though pyproject.toml is present, the --no-use-pep517 option is
available (although obviously it is an error to choose --no-use-pep517 if
the project has no setup.py, or explicitly requests a build backend). As
with other command line flags, pip recognises the PIP_USE_PEP517
environment veriable and a use-pep517 config file option (set to true or
false) to set this option globally. Note that overriding pip’s choice of
whether to use PEP 517 processing in this way does not affect whether pip
will use an isolated build environment (which is controlled via
--no-build-isolation as noted above).

Except in the case noted above (projects with no PEP 518[build-system]
section in pyproject.toml), pip will never implicitly install a build
system. Projects must ensure that the correct build system is listed in
their requires list (this applies even if pip assumes that the
setuptools backend is being used, as noted above).

Historical Limitations:

pip<18.0: only supports installing build requirements from wheels, and
does not support the use of environment markers and extras (only version
specifiers are respected).

pip<18.1: build dependencies using .pth files are not properly supported;
as a result namespace packages do not work under Python 3.2 and earlier.

PEP 426 notes that the intention is to add hooks to project metadata in
version 2.1 of the metadata spec, to explicitly define how to build a project
from its source. Once this version of the metadata spec is final, pip will
migrate to using that interface. At that point, the setup.py interface
documented here will be retained solely for legacy purposes, until projects
have migrated.

Specifically, applications should not expect to rely on there being any form
of backward compatibility guarantees around the setup.py interface.

The --global-option and --build-option arguments to the pipinstall
and pipwheel inject additional arguments into the setup.py command
(--build-option is only available in pipwheel). These arguments are
included in the command as follows:

pythonsetup.py<global_options>BUILDCOMMAND<build_options>

The options are passed unmodified, and presently offer direct access to the
distutils command line. Use of --global-option and --build-option
should be considered as build system dependent, and may not be supported in the
current form if support for alternative build systems is added to pip.