{"record":{"id":"c68d348b8827955a","repo":"apache/beam","slug":"could-not-find-python-executable","errorCode":null,"errorMessage":"Could not find Python executable.","messagePattern":"Could not find Python executable\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/portability/stager.py","lineNumber":690,"sourceCode":"    with open(os.path.join(temp_dir, EXTRA_PACKAGES_FILE), 'wt') as f:\n      for package in local_packages:\n        f.write('%s\\n' % os.path.basename(package))\n    # Note that the caller of this function is responsible for deleting the\n    # temporary folder where all temp files are created, including this one.\n    resources.append(\n        Stager._create_file_stage_to_artifact(\n            os.path.join(temp_dir, EXTRA_PACKAGES_FILE), EXTRA_PACKAGES_FILE))\n\n    return resources\n\n  @staticmethod\n  def _get_python_executable():\n    # Allow overriding the python executable to use for downloading and\n    # installing dependencies, otherwise use the python executable for\n    # the current process.\n    python_bin = os.environ.get('BEAM_PYTHON') or sys.executable\n    if not python_bin:\n      raise ValueError('Could not find Python executable.')\n    return python_bin\n\n  @staticmethod\n  def _remove_dependency_from_requirements(\n      requirements_file: str, dependency_to_remove: str, temp_directory_path):\n    \"\"\"Function to remove dependencies from a given requirements file.\"\"\"\n    # read all the dependency names\n    with open(requirements_file, 'r') as f:\n      lines = f.readlines()\n\n    tmp_requirements_filename = os.path.join(\n        temp_directory_path, 'tmp_requirements.txt')\n\n    with open(tmp_requirements_filename, 'w') as tf:\n      for i in range(len(lines)):\n        if not lines[i].startswith(dependency_to_remove):\n          tf.write(lines[i])\n","sourceCodeStart":672,"sourceCodeEnd":708,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/portability/stager.py#L672-L708","documentation":"Raised by Stager._get_python_executable when neither the BEAM_PYTHON environment variable nor sys.executable yields a usable Python binary. It ensures dependency installation during staging runs with a valid interpreter. Since sys.executable is normally set, this almost always means BEAM_PYTHON was set to an empty or invalid value.","triggerScenarios":"Setting BEAM_PYTHON to an empty string (or otherwise falsy) while sys.executable is also empty/None, e.g. running embedded in an interpreter without a resolved executable.","commonSituations":"BEAM_PYTHON='' exported in CI or Docker images; running under embedded Python or frozen binaries where sys.executable is empty.","solutions":["Unset or correctly set the BEAM_PYTHON environment variable to a valid python binary path","Ensure the pipeline is launched from a normal Python interpreter where sys.executable is populated","Verify the BEAM_PYTHON path exists and is executable (e.g. BEAM_PYTHON=$(which python3))"],"exampleFix":"# before\nexport BEAM_PYTHON=\"\"\n# after\nexport BEAM_PYTHON=$(which python3)","handlingStrategy":"validation","validationCode":"import os, sys\npython_bin = os.environ.get('BEAM_PYTHON') or sys.executable\nif not python_bin:\n    raise SystemExit('Set BEAM_PYTHON to a valid python binary before launching.')","typeGuard":"def has_python_executable() -> bool:\n    import shutil\n    bin_ = os.environ.get('BEAM_PYTHON') or sys.executable\n    return bool(bin_) and (shutil.which(bin_) is not None or os.path.isfile(bin_))","tryCatchPattern":"try:\n    stage_dependencies(...)\nexcept ValueError as e:\n    if 'Could not find Python executable' in str(e):\n        os.environ['BEAM_PYTHON'] = sys.executable or shutil.which('python3')\n    raise","preventionTips":["Never export BEAM_PYTHON as an empty string in CI or Dockerfiles","Validate BEAM_PYTHON resolves to an executable at environment bootstrap","Prefer running pipelines from a standard CPython interpreter where sys.executable is set"],"tags":["python","apache-beam","environment","executable"],"backgroundTag":"missing-env-var","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}