{"record":{"id":"161ae032870e3dcb","repo":"pypa/pip","slug":"could-not-locate-python-interpreter-python","errorCode":null,"errorMessage":"Could not locate Python interpreter {python}","messagePattern":"Could not locate Python interpreter (.+?)","errorType":"exception","errorClass":"CommandError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/cli/main_parser.py","lineNumber":88,"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":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/cli/main_parser.py#L70-L106","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Verify the path exists: `ls -l <path>` and confirm it is an executable or a venv containing bin/python.","Use an absolute path to the interpreter, e.g. `pip --python /opt/venv/bin/python install <pkg>`.","If targeting a venv directory, ensure it was created normally (`python -m venv <dir>`) so bin/python is present."],"exampleFix":"# before\npip install --python /opt/venv <pkg>\n# after\npip install --python /opt/venv/bin/python <pkg>","handlingStrategy":"validation","validationCode":"# Replicate identify_python_interpreter's logic to validate before calling pip.\nimport os\ndef resolve_python(p):\n    if os.path.exists(p):\n        if os.path.isdir(p):\n            for exe in (\"bin/python\", \"Scripts/python.exe\"):\n                cand = os.path.join(p, exe)\n                if os.path.exists(cand):\n                    return cand\n        else:\n            return p\n    raise FileNotFoundError(f\"Could not locate Python interpreter {p}\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer absolute paths to the interpreter binary for --python.","If pointing at a directory, ensure it is a real venv with bin/python."],"tags":["cli-options","python-interpreter","path","command-error"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}