{"record":{"id":"46b50a8329b7b6ff","repo":"PyO3/pyo3","slug":"failed-to-run-the-python-interpreter-at","errorCode":null,"errorMessage":"failed to run the Python interpreter at {}: {}","messagePattern":"failed to run the Python interpreter at (.+?): (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pyo3-build-config/src/impl_.rs","lineNumber":2529,"sourceCode":"{\n    let out = Command::new(interpreter)\n        .env(\"PYTHONIOENCODING\", \"utf-8\")\n        .envs(envs)\n        .stdin(Stdio::piped())\n        .stdout(Stdio::piped())\n        .stderr(Stdio::inherit())\n        .spawn()\n        .and_then(|mut child| {\n            child\n                .stdin\n                .as_mut()\n                .expect(\"piped stdin\")\n                .write_all(script.as_bytes())?;\n            child.wait_with_output()\n        });\n\n    match out {\n        Err(err) => bail!(\n            \"failed to run the Python interpreter at {}: {}\",\n            interpreter.display(),\n            err\n        ),\n        Ok(ok) if !ok.status.success() => bail!(\"Python script failed\"),\n        Ok(ok) => Ok(String::from_utf8(ok.stdout)\n            .context(\"failed to parse Python script output as utf-8\")?),\n    }\n}\n\nfn venv_interpreter(virtual_env: &OsStr, windows: bool) -> PathBuf {\n    let venv = Path::new(virtual_env);\n    // Rebuild if the virtual environment configuration changes\n    println!(\n        \"cargo:rerun-if-changed={}\",\n        venv.join(\"pyvenv.cfg\").display()\n    );\n    if windows {","sourceCodeStart":2511,"sourceCodeEnd":2547,"githubUrl":"https://github.com/PyO3/pyo3/blob/ac9b6899d348be4d54614d060dea53a645a12e36/pyo3-build-config/src/impl_.rs#L2511-L2547","documentation":"pyo3's build config runs the configured Python interpreter via run_python_script to probe interpreter properties. If spawning or piping to the interpreter process fails at the OS level (the Err branch of the result), the build fails with this message, which embeds the interpreter path and the underlying io::Error.","triggerScenarios":"The interpreter path stored in the config does not exist, lacks execute permission, or the process cannot be spawned (ENOENT, EACCES); stdin piping to the child fails; the interpreter binary is corrupt or an incompatible executable for the platform.","commonSituations":"PYO3_PYTHON points to a removed or relocated interpreter; cross-compiling with a host python path that is not runnable on the build host; Windows Store python stub executables; a venv was deleted but PYO3_PYTHON/VIRTUAL_ENV still reference it.","solutions":["Verify the interpreter path in the error actually exists and runs: `<path> -c \"print(1)\"`","Set PYO3_PYTHON to a working interpreter (or activate the correct venv) and rebuild","If cross-compiling, ensure the interpreter is executable on the machine running the build script","Clean stale caches (cargo clean) and re-check VIRTUAL_ENV/PYTHON_HOME pointing at a deleted venv"],"exampleFix":"// shell, before\nPYO3_PYTHON=/opt/old/python3.9 cargo build   # ENOENT\n// after\nPYO3_PYTHON=$(which python3.12) cargo build","handlingStrategy":"validation","validationCode":"// shell\nif [ ! -x \"${PYO3_PYTHON:-python3}\" ]; then echo \"interpreter missing/unrunnable: $PYO3_PYTHON\"; fi\n\"${PYO3_PYTHON:-python3}\" -c 'print(\"ok\")' || echo 'interpreter cannot execute'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set PYO3_PYTHON explicitly in CI and Docker images","Verify interpreter executability after container/venv changes","Avoid referencing venv interpreters that may be recreated at different paths"],"tags":["rust","pyo3","python-interpreter","process-spawn","build-time"],"backgroundTag":"interpreter-not-found","analyzedSha":"ac9b6899d348be4d54614d060dea53a645a12e36","analyzedAt":"2026-09-05T09:20:35.319Z","contentChangedAt":"2026-09-05T09:20:35.319Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}