pypa/pip · error · CommandError

Could not locate Python interpreter {general_options.python}

Error message

Could not locate Python interpreter {general_options.python}

What it means

Raised by parse_command() in main_parser.py:87 when the --python option is used but identify_python_interpreter() cannot find the specified interpreter. The function checks if the path exists; if it's a directory, it looks for bin/python or Scripts/python.exe within it. If nothing is found, it returns None and this error is raised.

Source

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

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

Solutions

Verify the path exists: `ls -la <path>` and check for the python binary.
Use an absolute path to the interpreter: `pip --python /usr/bin/python3.12 install foo`.
If pointing to a venv directory, ensure it contains bin/python (Unix) or Scripts/python.exe (Windows).
Activate the venv first and run pip without --python.

Example fix

# before
pip --python ~/envs/myenv install foo

# after
pip --python ~/envs/myenv/bin/python install foo
# or activate first:
source ~/envs/myenv/bin/activate && pip install foo

Defensive patterns

Strategy: validation

Validate before calling

import os
def validate_python_interpreter(path):
    """Check if the path points to a usable Python interpreter or venv."""
    if not os.path.exists(path):
        return False
    if os.path.isdir(path):
        for exe in ('bin/python', 'Scripts/python.exe'):
            if os.path.exists(os.path.join(path, exe)):
                return True
        return False
    return True

Type guard

def is_valid_python_path(path: str) -> bool:
    import os
    if not os.path.exists(path):
        return False
    if os.path.isdir(path):
        return any(os.path.exists(os.path.join(path, e)) for e in ('bin/python', 'Scripts/python.exe'))
    return True

Try / catch

from pip._internal.exceptions import CommandError
try:
    # pip --python <path> install ...
except CommandError as e:
    if 'Could not locate Python interpreter' in str(e):
        # verify path, use absolute path to venv/bin/python

Prevention

Always use absolute paths for --python.
Verify the interpreter exists before referencing it.
For venvs, point to the venv directory or activate it first.

When it happens

Trigger: Calling `pip --python /nonexistent/python install foo` or `pip --python /path/to/venv install foo` where the venv directory doesn't contain a python executable in bin/ or Scripts/. Also triggered by `pip --python python3.99 install foo` where python3.99 is not on PATH (but this case is less likely since bare names are not resolved via PATH).

Common situations: Typo in the interpreter path. Referencing a venv that was deleted or never created. Using a relative path that doesn't resolve from the current working directory. Pointing to a venv directory with a non-standard layout.

Related errors

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