Running pip & General Options

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the Python Reference bibliography.

pip is a command-line program with one set of general options shared by every command (install, list, download, …) and per-command options documented on the other pip pages. This page covers the general ones, as printed by python -m pip --help for pip 26.2.2 on CPython 3.14.6 on 2026-10-22. Every option also has a PIP_<NAME> environment variable and a configuration-file form, described on pip: Configuration.

Invoking pip

python -m pip <command> [options]

Use python -m pip (or py -m pip on Windows) rather than the bare pip, for the reasons on Installing & Upgrading pip. General options can go before or after the command name. --python <python> (pip 22.3) runs pip as if it had been started from another interpreter or venv; see Environments & Externally Managed Pythons.

Source: pip user guide: Running pip, pip: Managing a different Python interpreter.

The general options

Option Default Meaning

-h, --help

Help for pip or for one command (python -m pip install --help).

--debug

off

Let unhandled exceptions propagate (show the Python traceback) instead of logging them.

--isolated

off

Ignore environment variables and user configuration; see below.

--require-virtualenv

off

Refuse to run outside a virtual environment (exit code 3). PIP_REQUIRE_VIRTUALENV.

--python <python>

the running Python

Run pip with another interpreter or venv (22.3). PIP_PYTHON.

-v, --verbose

More output; up to three times (-vvv).

-V, --version

Print the pip version, its location and its Python.

-q, --quiet

Less output; up to three times (WARNING, ERROR, CRITICAL).

--log <path>

none

Append a maximum-verbosity log to this file, whatever the console level. PIP_LOG.

--no-input

off

Never prompt (credentials, confirmations). PIP_NO_INPUT.

--keyring-provider

auto

How to look credentials up: auto, disabled, import, subprocess. See Authentication, Proxies & Certificates.

--proxy <proxy>

none

scheme://[user:passwd@]proxy.server:port.

--no-proxy-env

off

Ignore proxies configured in non-pip environment variables or files (26.2); --proxy still applies.

--retries <n>

5

Maximum attempts to establish a new HTTP connection.

--timeout <sec>

15

Socket timeout in seconds.

--resume-retries <n>

5

Attempts to resume or restart an incomplete download (option added in 25.1, automatic resume since 25.2).

--exists-action <action>

prompt

What to do when a path exists: s switch, i ignore, w wipe, b backup, a abort.

--trusted-host <host>

none

Treat a host as trusted even without valid HTTPS. Avoid it.

--cert <path>

system store

A PEM CA bundle that replaces the default.

--client-cert <path>

none

A PEM file with a client private key and certificate.

--cache-dir <dir>

per OS

Where the HTTP and wheel caches live. --no-cache-dir disables them.

--disable-pip-version-check

off

Do not check PyPI for a newer pip. Implied by --no-index.

--no-color

off

No coloured output.

--use-feature <feature>

Opt in to new behaviour: fast-deps, inprocess-build-deps, venv-isolation, truststore, no-binary-enable-wheel-cache, build-constraint.

--use-deprecated <feature>

Opt back in to old behaviour: legacy-resolver, legacy-certs.

The --use-feature and --use-deprecated values above are the complete lists accepted by pip 26.2.2, taken from its own error message for an invalid choice. Several are no-ops kept for compatibility: truststore is the default since 24.2 and build-constraint has been always on since 26.2. venv-isolation (26.2) and inprocess-build-deps (26.0) are experimental; see pip: Build System Interface. The deprecation process behind the two flags is on pip: Versions & Release History.

Source: pip: General options.

--require-virtualenv

PIP_REQUIRE_VIRTUALENV=1 python3.14 -m pip install tomli-w
echo "exit=$?"
ERROR: Could not find an activated virtualenv (required).
exit=3

The check applies to commands that change an environment. Read-only commands such as pip list still run outside a venv with the option set. Setting require-virtualenv = true in your user pip.conf is a cheap guard against installing into a system Python by accident.

Source: pip: --require-virtualenv.

--isolated

--isolated makes pip ignore every PIP_* environment variable and the user configuration file, so that a command behaves the same on every machine. Use it to find out whether a surprising behaviour comes from your configuration.

--exists-action

When pip would overwrite something (a VCS checkout for an editable install, a downloaded file, an archive), it asks, unless --exists-action (PIP_EXISTS_ACTION) gives the answer: s`witch the checkout to the new URL or revision, `i`gnore and skip the operation, `w`ipe and start again, `b`ackup by renaming to `{name}.bak, or a`bort with a non-zero exit code. In CI, set it together with `--no-input.

Source: pip: --exists-action option.

Logging

Console verbosity is set with -v and -q; --no-color removes colours. --log <file> keeps a separate, always maximum-verbosity log that is appended to, which is the thing to attach to a bug report. Even a -q run fills it:

python -m pip install --log pip.log -q tomli-w
grep -E 'Successfully|Collecting|Installing' pip.log
2026-10-22T17:15:29,066 Collecting tomli-w
2026-10-22T17:15:29,098 Installing collected packages: tomli-w
2026-10-22T17:15:29,109 Successfully installed tomli-w-1.2.0

Source: pip: Logging, pip: Console logging, pip: File logging.

--progress-bar and --root-user-action

Two options that belong to install, download and wheel but matter whenever pip runs unattended:

  • --progress-bar auto|on|off|raw (default auto). auto (25.2) shows bars only on a terminal and is silenced by --quiet; since 26.2 bars and spinners never animate on CI, even with FORCE_COLOR. raw prints machine-readable progress lines for a program that wraps pip.

  • --root-user-action warn|ignore (default warn). Running pip as root prints a warning that it may break the system’s packages; ignore silences it in container builds where root is normal.

Source: pip install: --progress-bar, pip install: --root-user-action.

Shell completion

pip completion prints a script for your shell:

python -m pip completion --bash >> ~/.profile
python -m pip completion --zsh >> ~/.zshrc
python -m pip completion --fish > ~/.config/fish/completions/pip.fish
python -m pip completion --powershell | Out-File -Encoding default -Append $PROFILE

The zsh script starts with a #compdef line and calls zsh’s completion system:

# pip zsh completion start
#compdef -P pip[0-9.]#
__pip() {
  compadd $( COMP_WORDS="$words[*]" \
             COMP_CWORD=$((CURRENT-1)) \
             PIP_AUTO_COMPLETE=1 $words[1] 2>/dev/null )
}
…

If your shell then reports command not found: compdef, completion is not initialised yet; put autoload -Uz compinit && compinit before the appended snippet in ~/.zshrc. Completion has its own section in the user guide; the old cli/pip_completion page no longer exists.

Source: pip user guide: Command completion.

Using pip from a program

pip has no supported Python API. import pip works, but the documentation is explicit that its internals assume sole control of logging and standard streams, are not thread-safe, assume the process ends afterwards, and may change in any release; "everything inside of pip is considered an implementation detail". The supported way is a subprocess that runs the same interpreter’s pip:

import json
import subprocess
import sys


def pip(*args: str) -> subprocess.CompletedProcess[str]:
    return subprocess.run([sys.executable, "-m", "pip", *args], check=True, capture_output=True, text=True)


pip("install", "--quiet", "tomli-w==1.2.0")
installed = json.loads(pip("list", "--format=json").stdout)
print({p["name"]: p["version"] for p in installed})
{'pip': '26.2.2', 'tomli_w': '1.2.0'}

For structured results use the JSON outputs pip offers: pip list --format=json, pip inspect, pip install --report - and pip index versions --json. To show progress in your own UI, pass --progress-bar=raw. Installing packages into sys.path of the running process can confuse the import system’s caches; restart or call importlib.invalidate_caches().

Source: pip user guide: Using pip from your program.

Exit codes

pip 26.2.2 defines these status codes in pip/_internal/cli/status_codes.py:

Code Name When

0

SUCCESS

The command succeeded.

1

ERROR

Any handled error: resolution failed, a build failed, pip show found nothing, pip check found broken requirements.

2

UNKNOWN_ERROR

An unhandled exception (a pip bug, or something pip did not expect).

3

VIRTUALENV_NOT_FOUND

--require-virtualenv outside a venv.

4

PREVIOUS_BUILD_DIR_ERROR

A PreviousBuildDirError: a leftover build directory blocked the operation.

23

NO_MATCHES_FOUND

pip search found nothing (the command itself no longer works against PyPI).

120

BROKEN_STDOUT

Output was piped to a program that exited early.

 
python -m pip show no-such-dist; echo "exit=$?"
WARNING: Package(s) not found: no-such-dist
exit=1

Source: pip 26.2.2 source: status_codes.py, pip show.

pip and Poetry

Poetry’s global options are fewer and different: -v/-vv/-vvv, -q, -n/--no-interaction, --ansi/--no-ansi, -C/--directory, -P/--project, --no-plugins and --no-cache. They are on Poetry: Commands Reference.

References