pypa/pip · error · CommandError

Failed to run pip under

Error message

Failed to run pip under {interpreter}: {exc}

What it means

Raised as CommandError by parse_command (main_parser.py:106) when re-invoking pip under the interpreter named by --python fails at the subprocess level. After identify_python_interpreter confirms the path exists (line 86), pip builds the command (lines 92-96) and runs subprocess.run (line 103); the except at line 105 catches subprocess.SubprocessError and OSError and wraps them. This means the interpreter exists but could not actually execute pip (e.g. the target lacks pip, is not executable, or the OS refused to spawn it).

Solutions

  1. Run the target interpreter directly to confirm it works: `<interpreter> -c 'import sys; print(sys.version)'`.
  2. Install pip into the target interpreter: `python -m ensurepip --upgrade` or `python -m pip install --upgrade pip`.
  3. Recreate the venv (`python -m venv --clear /opt/venv`) if it is corrupt.
  4. Fix permissions/ownership on the interpreter binary if the OS refused to spawn it.

Example fix

# before (target venv lacks pip)
pip --python /opt/venv/bin/python install requests
# after (bootstrap pip in the target first)
/opt/venv/bin/python -m ensurepip --upgrade
pip --python /opt/venv/bin/python install requests
Defensive patterns

Strategy: try-catch

Validate before calling

# Pre-flight the target interpreter can run and has pip.
import subprocess
def check_target_interp(path):
    subprocess.check_call([path, "-c", "import sys, pip; print(sys.version, pip.__version__)"])
    return True

Try / catch

# Catch the wrapped CommandError when re-invoking pip programmatically.
from pip._internal.exceptions import CommandError
try:
    parse_command(["--python", interp, "install", pkg])
except CommandError as e:
    if "Failed to run pip under" in str(e):
        # bootstrap pip in target then retry
        subprocess.call([interp, "-m", "ensurepip", "--upgrade"])
    else:
        raise

Prevention

When it happens

Trigger: `pip --python /opt/venv/bin/python install <pkg>` where the venv's python is broken, lacks a runnable pip module, has restrictive permissions, or the binary is for the wrong architecture.

Common situations: Targeting a minimal/embedded Python without pip installed; pointing at a 32/64-bit-mismatched interpreter; corrupt venv; permission denied on the interpreter binary; PATH issues making get_runnable_pip() resolve to nothing.

Related errors

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/ddb3bbabf306b831. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_internal/cli/main_parser.py:106

            raise CommandError(
                f"Could not locate Python interpreter {general_options.python}"
            )

        pip_cmd = [
            interpreter,
            get_runnable_pip(),
        ]
        pip_cmd.extend(args)

        # Set a flag so the child doesn't re-invoke itself, causing
        # an infinite loop.
        os.environ["_PIP_RUNNING_IN_SUBPROCESS"] = "1"
        returncode = 0
        try:
            proc = subprocess.run(pip_cmd)
            returncode = proc.returncode
        except (subprocess.SubprocessError, OSError) as exc:
            raise CommandError(f"Failed to run pip under {interpreter}: {exc}")
        sys.exit(returncode)

    # --version
    if general_options.version:
        sys.stdout.write(parser.version)
        sys.stdout.write(os.linesep)
        sys.exit()

    # pip || pip help -> print_help()
    if not args_else or (args_else[0] == "help" and len(args_else) == 1):
        parser.print_help()
        sys.exit()

    # the subcommand name
    cmd_name = args_else[0]

    if cmd_name not in commands_dict:
        guess = get_similar_commands(cmd_name)

View on GitHub (pinned to f399c37189)