pypa/pip · error · CommandError

Could not locate Python interpreter {python}

Error message

Could not locate Python interpreter {python}

What it means

Raised as CommandError by parse_command (main_parser.py:88) when the --python option names an interpreter that identify_python_interpreter cannot resolve. That helper (lines 52-68) returns the path if it is an existing file, looks inside a directory for bin/python or Scripts/python.exe, and returns None otherwise. The error means neither a usable executable nor a venv-like directory was found at the given path.

Source

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

def parse_command(args: list[str]) -> tuple[str, list[str]]:
    parser = create_main_parser()

    # Note: parser calls disable_interspersed_args(), so the result of this
    # call is to split the initial args into the general options before the
    # subcommand and everything else.
    # For example:
    #  args: ['--timeout=5', 'install', '--user', 'INITools']
    #  general_options: ['--timeout==5']
    #  args_else: ['install', '--user', 'INITools']
    general_options, args_else = parser.parse_args(args)

    # --python
    if general_options.python and "_PIP_RUNNING_IN_SUBPROCESS" not in os.environ:
        # Re-invoke pip using the specified Python interpreter
        interpreter = identify_python_interpreter(general_options.python)
        if interpreter is None:
            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}")

View on GitHub (pinned to f399c37189)

Solutions

1. Verify the path exists: `ls -l <path>` and confirm it is an executable or a venv containing bin/python.
2. Use an absolute path to the interpreter, e.g. `pip --python /opt/venv/bin/python install <pkg>`.
3. If targeting a venv directory, ensure it was created normally (`python -m venv <dir>`) so bin/python is present.

Example fix

# before
pip install --python /opt/venv <pkg>
# after
pip install --python /opt/venv/bin/python <pkg>

# Replicate identify_python_interpreter's logic to validate before calling pip.
import os
def resolve_python(p):
    if os.path.exists(p):
        if os.path.isdir(p):
            for exe in ("bin/python", "Scripts/python.exe"):
                cand = os.path.join(p, exe)
                if os.path.exists(cand):
                    return cand
        else:
            return p
    raise FileNotFoundError(f"Could not locate Python interpreter {p}")

When it happens

Trigger: `pip install --python ./missing-python <pkg>`, `pip --python /opt/venv install <pkg>` where /opt/venv has no bin/python, or a typo in the interpreter path.

Common situations: Pointing --python at a venv directory that was created with --without-pip or is otherwise incomplete; relative paths that don't resolve from pip's working directory; using a pyenv shim name instead of a real path.

Related errors

• Cannot combine '--path' with '--user' or '--local'
• Failed to run pip under {interpreter}: {exc}
• Cannot use '--only-dependencies' in combination with {confli
• When restricting platform and interpreter constraints using
• Can not use any platform or abi specific options unless inst

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