{"record":{"id":"bd21f883f4978bc6","repo":"bazelbuild/bazel","slug":"could-not-find-python-binary-python-binary","errorCode":null,"errorMessage":"Could not find python binary: {PYTHON_BINARY}","messagePattern":"Could not find python binary: (.+?)","errorType":"panic","errorClass":"AssertionError","httpStatus":null,"severity":"critical","filePath":"tools/python/python_bootstrap_template.txt","lineNumber":502,"sourceCode":"  new_env['PYTHONPATH'] = python_path\n  runfiles_envkey, runfiles_envvalue = RunfilesEnvvar(module_space)\n  if runfiles_envkey:\n    new_env[runfiles_envkey] = runfiles_envvalue\n\n  # Don't prepend a potentially unsafe path to sys.path\n  # See: https://docs.python.org/3.11/using/cmdline.html#envvar-PYTHONSAFEPATH\n  new_env['PYTHONSAFEPATH'] = '1'\n\n  main_filename = os.path.join(module_space, main_rel_path)\n  main_filename = GetWindowsPathWithUNCPrefix(main_filename)\n  assert os.path.exists(main_filename), \\\n         'Cannot exec() %r: file not found.' % main_filename\n  assert os.access(main_filename, os.R_OK), \\\n         'Cannot exec() %r: file not readable.' % main_filename\n\n  program = python_program = FindPythonBinary(module_space)\n  if python_program is None:\n    raise AssertionError('Could not find python binary: ' + PYTHON_BINARY)\n\n  # COVERAGE_DIR is set if coverage is enabled and instrumentation is configured\n  # for something, though it could be another program executing this one or\n  # one executed by this one (e.g. an extension module).\n  if os.environ.get('COVERAGE_DIR'):\n    cov_tool = FindCoverageEntryPoint(module_space)\n    if cov_tool is None:\n      PrintVerboseCoverage('Coverage was enabled, but python coverage tool was not configured.')\n    else:\n      # Inhibit infinite recursion:\n      if 'PYTHON_COVERAGE' in os.environ:\n        del os.environ['PYTHON_COVERAGE']\n\n      if not os.path.exists(cov_tool):\n        raise EnvironmentError(\n          'Python coverage tool %r not found. '\n          'Try running with VERBOSE_COVERAGE=1 to collect more information.'\n          % cov_tool","sourceCodeStart":484,"sourceCodeEnd":520,"githubUrl":"https://github.com/bazelbuild/bazel/blob/e6e199d0601a244511b4cf18c8b2828aa73db1fd/tools/python/python_bootstrap_template.txt#L484-L520","documentation":"Final guard in the Python launcher: FindPythonBinary(module_space) returned None, so the interpreter named by PYTHON_BINARY could not be located via runfiles, absolute path, repo-relative path, or PATH search. The AssertionError echoes the configured PYTHON_BINARY value so you can see what was searched for.","triggerScenarios":"PYTHON_BINARY is a bare name (e.g. 'python3') not present on PATH of the execution environment; a repo-relative interpreter path that does not exist in the runfiles; the interpreter's runfiles entry missing because its target is not in the stub's deps.","commonSituations":"Running a bazel-built python binary in a container/VM without the interpreter installed; PATH stripped in the action's env; --python_path pointing at a nonexistent interpreter; sandboxed execution removing PATH entries.","solutions":["Check the PYTHON_BINARY value in the message: if it is a name, ensure that interpreter exists on PATH of the environment where the binary runs.","If it is a path, verify the file exists (absolute) or is present under the runfiles root (repo-relative).","Install the required interpreter in the execution environment or point --python_path/--python_top at a valid absolute interpreter."],"exampleFix":"# before\nbazel build //my:tool --python_path=python3.11  # not installed\n\n# after\nbazel build //my:tool --python_path=/usr/bin/python3  # verified absolute interpreter","handlingStrategy":"validation","validationCode":"import shutil, os\nassert os.path.isabs(PYTHON_BINARY) and os.path.exists(PYTHON_BINARY) or shutil.which(PYTHON_BINARY), \\\n    'interpreter %r unavailable' % PYTHON_BINARY","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin --python_path to an absolute interpreter path that exists in the execution environment.","For containers/CI, install the interpreter and verify 'python3 --version' before running bazel-built tools."],"tags":["python","interpreter","bazel","bootstrap"],"backgroundTag":null,"analyzedSha":"e6e199d0601a244511b4cf18c8b2828aa73db1fd","analyzedAt":"2026-08-14T10:24:27.848Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}