{"record":{"id":"ddb3bbabf306b831","repo":"pypa/pip","slug":"failed-to-run-pip-under-interpreter-exc","errorCode":null,"errorMessage":"Failed to run pip under {interpreter}: {exc}","messagePattern":"Failed to run pip under (.+?): (.+?)","errorType":"exception","errorClass":"CommandError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/cli/main_parser.py","lineNumber":106,"sourceCode":"            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}\")\n        sys.exit(returncode)\n\n    # --version\n    if general_options.version:\n        sys.stdout.write(parser.version)\n        sys.stdout.write(os.linesep)\n        sys.exit()\n\n    # pip || pip help -> print_help()\n    if not args_else or (args_else[0] == \"help\" and len(args_else) == 1):\n        parser.print_help()\n        sys.exit()\n\n    # the subcommand name\n    cmd_name = args_else[0]\n\n    if cmd_name not in commands_dict:\n        guess = get_similar_commands(cmd_name)","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/cli/main_parser.py#L88-L124","documentation":"Raised as CommandError by parse_command (main_parser.py:106) when re-invoking pip under the interpreter named by --python fails at the subprocess level. After identify_python_interpreter confirms the path exists (line 86), pip builds the command (lines 92-96) and runs subprocess.run (line 103); the except at line 105 catches subprocess.SubprocessError and OSError and wraps them. This means the interpreter exists but could not actually execute pip (e.g. the target lacks pip, is not executable, or the OS refused to spawn it).","triggerScenarios":"`pip --python /opt/venv/bin/python install <pkg>` where the venv's python is broken, lacks a runnable pip module, has restrictive permissions, or the binary is for the wrong architecture.","commonSituations":"Targeting a minimal/embedded Python without pip installed; pointing at a 32/64-bit-mismatched interpreter; corrupt venv; permission denied on the interpreter binary; PATH issues making get_runnable_pip() resolve to nothing.","solutions":["Run the target interpreter directly to confirm it works: `<interpreter> -c 'import sys; print(sys.version)'`.","Install pip into the target interpreter: `python -m ensurepip --upgrade` or `python -m pip install --upgrade pip`.","Recreate the venv (`python -m venv --clear /opt/venv`) if it is corrupt.","Fix permissions/ownership on the interpreter binary if the OS refused to spawn it."],"exampleFix":"# before (target venv lacks pip)\npip --python /opt/venv/bin/python install requests\n# after (bootstrap pip in the target first)\n/opt/venv/bin/python -m ensurepip --upgrade\npip --python /opt/venv/bin/python install requests","handlingStrategy":"try-catch","validationCode":"# Pre-flight the target interpreter can run and has pip.\nimport subprocess\ndef check_target_interp(path):\n    subprocess.check_call([path, \"-c\", \"import sys, pip; print(sys.version, pip.__version__)\"])\n    return True","typeGuard":null,"tryCatchPattern":"# Catch the wrapped CommandError when re-invoking pip programmatically.\nfrom pip._internal.exceptions import CommandError\ntry:\n    parse_command([\"--python\", interp, \"install\", pkg])\nexcept CommandError as e:\n    if \"Failed to run pip under\" in str(e):\n        # bootstrap pip in target then retry\n        subprocess.call([interp, \"-m\", \"ensurepip\", \"--upgrade\"])\n    else:\n        raise","preventionTips":["Ensure pip is installed in any interpreter you target with --python (ensurepip).","Validate the interpreter binary matches the host architecture and is executable."],"tags":["cli-options","python-interpreter","subprocess","command-error"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}