apache/beam · error

no python installation found

Error message

no python installation found: %v

What it means

SetUpPythonEnvironment prepares a virtualenv for the Apache Beam Python SDK to run an expansion service module. It first calls GetPythonVersion() to locate a usable python3 executable; if that fails, it wraps the failure with "no python installation found". This surfaces environment problems early instead of failing later when launching the Python expansion service.

Solutions

1. Install Python 3 and ensure the `python3` executable is on PATH (e.g. apt-get install python3 / brew install python).
2. Verify with `python3 --version` in the same environment/shell the Go job runs in.
3. If Python exists under a nonstandard path, extend PATH before starting the pipeline.
4. For containers, use a base image that includes Python 3 or install it in the Dockerfile.

Example fix

// before
runner, err := expansionx.SetUpPythonEnvironment(extraPackage)
// after (pre-check in caller)
if _, err := exec.LookPath("python3"); err != nil {
    return fmt.Errorf("python3 must be installed and on PATH before starting python expansion service: %w", err)
}
runner, err := expansionx.SetUpPythonEnvironment(extraPackage)

if _, err := exec.LookPath("python3"); err != nil {
    return fmt.Errorf("python3 not found on PATH: %w", err)
}

runner, err := expansionx.SetUpPythonEnvironment(extra)
if err != nil {
    if strings.Contains(err.Error(), "no python installation found") {
        return fmt.Errorf("install Python 3 and add it to PATH: %w", err)
    }
    return err
}

When it happens

Trigger: Calling SetUpPythonEnvironment (directly or via startPythonExpansionService) on a machine where no python3 binary is on PATH, where the found python is too old, or where GetPythonVersion's exec of `python3 --version` errors.

Common situations: CI containers without Python installed; PATH not including the Python install directory; minimal Docker images (e.g. distroless); users with only `python` (2.x) and no `python3`.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• No proto encoding for PaneInfoCoder, always part of…
• no python installation found. If you use a custom container…
• Can't find a Python executable.
• cannot pull dev versions of JARs, please run "gradlew
• Could not find coder for URN " + urn

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/85fa13eacbaffb0b. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/core/runtime/xlangx/expansionx/download.go:444

		return pythonPath, nil
	}
	for _, v := range []string{"python", "python3"} {
		cmd := exec.Command(v, "--version")
		if err := cmd.Run(); err == nil {
			return v, nil
		}
	}
	return "", errors.New("no python installation found. If you use a " +
		"custom container image, please check if python/python3 is available or specify the " +
		"full path to the python interpreter in PYTHON_PATH environment variable")
}

// SetUpPythonEnvironment sets up the virtual ennvironment required for the
// Apache Beam Python SDK to run an expansion service module.
func SetUpPythonEnvironment(extraPackage string) (string, error) {
	py, err := GetPythonVersion()
	if err != nil {
		return "", fmt.Errorf("no python installation found: %v", err)
	}
	extraPackages := []string{}
	if len(extraPackage) > 0 {
		extraPackages = strings.Split(extraPackage, " ")
	}

	// create python virtual environment
	sort.Strings(extraPackages)
	beamPackage := fmt.Sprintf("apache_beam[gcp,aws,azure,dataframe]==%s", core.SdkVersion)
	venvDir := filepath.Join(
		cacheDir, "venvs",
		fmt.Sprintf("py-%s-beam-%s-%s", py, core.SdkVersion, strings.Join(extraPackages, ";")),
	)
	venvPython := filepath.Join(venvDir, "bin", "python")

	if _, err := os.Stat(venvPython); err != nil {
		err := exec.Command(py, "-m", "venv", venvDir).Run()
		if err != nil {

View on GitHub (pinned to 12126d8942)