{"id":"1c56e31d7f7f6d84","repo":"pypa/pip","slug":"could-not-locate-python-interpreter-general-optio","errorCode":null,"errorMessage":"Could not locate Python interpreter {general_options.python}","messagePattern":"Could not locate Python interpreter (.+?)","errorType":"exception","errorClass":"CommandError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/cli/main_parser.py","lineNumber":87,"sourceCode":"\ndef parse_command(args: list[str]) -> tuple[str, list[str]]:\n    parser = create_main_parser()\n\n    # Note: parser calls disable_interspersed_args(), so the result of this\n    # call is to split the initial args into the general options before the\n    # subcommand and everything else.\n    # For example:\n    #  args: ['--timeout=5', 'install', '--user', 'INITools']\n    #  general_options: ['--timeout==5']\n    #  args_else: ['install', '--user', 'INITools']\n    general_options, args_else = parser.parse_args(args)\n\n    # --python\n    if general_options.python and \"_PIP_RUNNING_IN_SUBPROCESS\" not in os.environ:\n        # Re-invoke pip using the specified Python interpreter\n        interpreter = identify_python_interpreter(general_options.python)\n        if interpreter is None:\n            raise CommandError(\n                f\"Could not locate Python interpreter {general_options.python}\"\n            )\n\n        pip_cmd = [\n            interpreter,\n            get_runnable_pip(),\n        ]\n        pip_cmd.extend(args)\n\n        # Set a flag so the child doesn't re-invoke itself, causing\n        # an infinite loop.\n        os.environ[\"_PIP_RUNNING_IN_SUBPROCESS\"] = \"1\"\n        returncode = 0\n        try:\n            proc = subprocess.run(pip_cmd)\n            returncode = proc.returncode\n        except (subprocess.SubprocessError, OSError) as exc:\n            raise CommandError(f\"Failed to run pip under {interpreter}: {exc}\")","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/cli/main_parser.py#L69-L105","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"# before\npip --python ~/envs/myenv install foo\n\n# after\npip --python ~/envs/myenv/bin/python install foo\n# or activate first:\nsource ~/envs/myenv/bin/activate && pip install foo","handlingStrategy":"validation","validationCode":"import os\ndef validate_python_interpreter(path):\n    \"\"\"Check if the path points to a usable Python interpreter or venv.\"\"\"\n    if not os.path.exists(path):\n        return False\n    if os.path.isdir(path):\n        for exe in ('bin/python', 'Scripts/python.exe'):\n            if os.path.exists(os.path.join(path, exe)):\n                return True\n        return False\n    return True","typeGuard":"def is_valid_python_path(path: str) -> bool:\n    import os\n    if not os.path.exists(path):\n        return False\n    if os.path.isdir(path):\n        return any(os.path.exists(os.path.join(path, e)) for e in ('bin/python', 'Scripts/python.exe'))\n    return True","tryCatchPattern":"from pip._internal.exceptions import CommandError\ntry:\n    # pip --python <path> install ...\nexcept CommandError as e:\n    if 'Could not locate Python interpreter' in str(e):\n        # verify path, use absolute path to venv/bin/python\n","preventionTips":["Always use absolute paths for --python.","Verify the interpreter exists before referencing it.","For venvs, point to the venv directory or activate it first."],"tags":["cli","python-interpreter","path","validation"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}