What causes "Failed to run pip under {interpreter}: {exc}" in pypa/pip?

Check execute permissions: `chmod +x ` if needed.

pypa/pip · error · CommandError

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

Error message

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

What it means

Raised by parse_command() in main_parser.py:105 when pip fails to spawn a subprocess using the interpreter specified by --python. After locating the interpreter, pip constructs a command list and calls subprocess.run(); if that raises subprocess.SubprocessError or OSError, the error is wrapped with the interpreter path and original exception message.

Source

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

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

Solutions

Check execute permissions: `chmod +x <interpreter>` if needed.
Verify the binary runs: `<interpreter> --version`.
Check for missing shared libraries: `ldd <interpreter>` (Linux).
If architecture mismatch, install a compatible Python build.
Reinstall or rebuild the Python interpreter.

Example fix

# before
pip --python /opt/brokenpython/bin/python install foo
# error: Failed to run pip under /opt/brokenpython/bin/python: ...

# after
chmod +x /opt/brokenpython/bin/python
# or verify and use a working interpreter:
pip --python /usr/bin/python3 install foo

Defensive patterns

Strategy: validation

Validate before calling

import os, stat
def validate_interpreter_executable(path):
    """Check if the interpreter is executable."""
    if not os.path.exists(path):
        return False
    if not os.access(path, os.X_OK):
        return False
    return stat.S_ISREG(os.stat(path).st_mode)

Try / catch

from pip._internal.exceptions import CommandError
try:
    # pip --python <interpreter> install ...
except CommandError as e:
    if 'Failed to run pip under' in str(e):
        # check permissions, architecture, shared libs

Prevention

Verify the interpreter runs: execute `<path> --version` before using --python.
Check execute permissions on the binary.
On Linux, use `ldd` to verify shared library dependencies.

When it happens

Trigger: Calling `pip --python /path/to/python install foo` where the located interpreter exists but cannot execute (e.g., permission denied, corrupt binary, wrong architecture, missing shared libraries). The subprocess.run call at main_parser.py:102 fails.

Common situations: The Python binary lacks execute permission. The binary is for a different CPU architecture (e.g., ARM binary on x86). Missing dynamic linker or shared libraries (common with manually compiled Python). The interpreter is a script rather than a binary that can't handle pip's arguments.

Related errors

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