xtekky/gpt4free · error

ensurepip failed (exit %d): %w

Error message

ensurepip failed (exit %d): %w

What it means

Error "ensurepip failed (exit %d): %w" thrown in xtekky/gpt4free.

Source

Thrown at g4f-go/runtime.go:148

	}
	if err := os.WriteFile(stamp, []byte("g4f installed"), 0o644); err != nil {
		return err
	}
	fmt.Printf("gpt4free installed in %.1fs\n", time.Since(start).Seconds())
	return nil
}

// ensurePip makes `python -m pip` available in the downloaded runtime.
// pbs installs ship ensurepip but no standalone pip; bootstrap once.
func ensurePip(binDir, exe string) error {
	code, err := runPython(noSignalCtx(), exe, []string{"-c", "import pip"}, pipEnv(binDir)...)
	if err == nil && code == 0 {
		return nil
	}
	fmt.Println("  bootstrapping pip (ensurepip)...")
	code, err = runPython(noSignalCtx(), exe, []string{"-m", "ensurepip", "--upgrade"}, pipEnv(binDir)...)
	if err != nil || code != 0 {
		return fmt.Errorf("ensurepip failed (exit %d): %w", code, err)
	}
	return nil
}

// pipEnv restricts pip to the downloaded runtime so installs never touch the
// host Python. pbs installs are a full layout: lib/pythonX.Y/site-packages
// (unix) or Lib/site-packages (windows) inside the interpreter home.
func pipEnv(binDir string) []string {
	home := pythonHome(binDir)
	lib := filepath.Join(home, "Lib", "site-packages")
	if runtime.GOOS != "windows" {
		lib = filepath.Join(home, "lib", "python3.14", "site-packages")
	}
	return []string{
		"PYTHONHOME=" + home,
		"PYTHONNOUSERSITE=1",
		"PYTHONDONTWRITEBYTECODE=1",
		"PYTHONUTF8=1",

View on GitHub (pinned to 973504e177)

Solutions

1. Re-extract the python runtime (delete the runtime dir and re-run) and retry ensurepip.

When it happens

Trigger: Thrown at g4f-go/runtime.go:148 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of xtekky/gpt4free@973504e177 (2026-08-14). Data as JSON: /api/errors/e5a7d3100a7678f2. Report an issue: GitHub.