no python installation found. If you use a custom container…

Error message

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

What it means

GetPythonVersion probes for a 'python' or 'python3' executable to set up the Python expansion service environment. If neither can be executed, it fails with guidance about custom container images and the PYTHON_PATH environment variable.

Solutions

Install python3 in the environment/container running the expansion service
Set PYTHON_PATH to the full path of the python interpreter (e.g. /usr/local/bin/python3)
Use a Beam SDK container image that includes Python, or base your custom image on a beam SDK image
Verify PATH inside the container: run `which python3` to confirm availability

Example fix

// before
cmd := exec.Command("go", "run")
// after
os.Setenv("PYTHON_PATH", "/usr/local/bin/python3") // in the environment launching the expansion service
cmd := exec.Command("go", "run")

Defensive patterns

Strategy: validation

Validate before calling

for _, v := range []string{"python", "python3", os.Getenv("PYTHON_PATH")} {
    if v == "" { continue }
    if p, err := exec.LookPath(v); err == nil { pythonBin = p; break }
}
if pythonBin == "" { return errors.New("no python interpreter on PATH; install python3 or set PYTHON_PATH") }

Try / catch

ver, err := expansionx.GetPythonVersion()
if err != nil {
    if strings.Contains(err.Error(), "no python installation found") {
        return fmt.Errorf("install python3 in the image or set PYTHON_PATH: %w", err)
    }
    return err
}

Prevention

Base custom containers on official Beam SDK images which include Python
Set PYTHON_PATH explicitly in Dockerfiles for slim images
Run `which python3` as a container smoke test
Document Python as a runtime requirement for cross-language expansion

When it happens

Trigger: Calling GetPythonVersion (indirectly via SetUpPythonEnvironment, setupVenv, pipInstallRequirements, logRuntimeDependencies, or starting the Python expansion service) on a host or container without python/python3 on PATH.

Common situations: Using a custom container image that lacks a Python runtime; running Go-only jobs that trigger xlang expansion without Python installed; Python installed under a non-PATH name or custom location; slim/distroless images without python.

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

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

Appendix: source

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

	_, err := os.Stat(jarPath)
	return err == nil
}

// GetPythonVersion returns the Python version to use. It checks for
// env variable PYTHON_PATH and returns that it if set.
// If no PYTHON_PATH is defined then it checks for python or python3
// and returns that. Otherwise it returns an error.
func GetPythonVersion() (string, error) {
	if pythonPath := os.Getenv("PYTHON_PATH"); pythonPath != "" {
		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)

View on GitHub (pinned to 12126d8942)