What causes "failed to run the Python interpreter at {}: {}" in PyO3/pyo3?

Verify the interpreter path in the error actually exists and runs: ` -c "print(1)"`

failed to run the Python interpreter at {}: {}

Error message

failed to run the Python interpreter at {}: {}

What it means

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.

Source

Thrown at pyo3-build-config/src/impl_.rs:2529

{
    let out = Command::new(interpreter)
        .env("PYTHONIOENCODING", "utf-8")
        .envs(envs)
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::inherit())
        .spawn()
        .and_then(|mut child| {
            child
                .stdin
                .as_mut()
                .expect("piped stdin")
                .write_all(script.as_bytes())?;
            child.wait_with_output()
        });

    match out {
        Err(err) => bail!(
            "failed to run the Python interpreter at {}: {}",
            interpreter.display(),
            err
        ),
        Ok(ok) if !ok.status.success() => bail!("Python script failed"),
        Ok(ok) => Ok(String::from_utf8(ok.stdout)
            .context("failed to parse Python script output as utf-8")?),
    }
}

fn venv_interpreter(virtual_env: &OsStr, windows: bool) -> PathBuf {
    let venv = Path::new(virtual_env);
    // Rebuild if the virtual environment configuration changes
    println!(
        "cargo:rerun-if-changed={}",
        venv.join("pyvenv.cfg").display()
    );
    if windows {

View on GitHub (pinned to ac9b6899d3)

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

Example fix

// shell, before
PYO3_PYTHON=/opt/old/python3.9 cargo build   # ENOENT
// after
PYO3_PYTHON=$(which python3.12) cargo build

Defensive patterns

Strategy: validation

Validate before calling

// shell
if [ ! -x "${PYO3_PYTHON:-python3}" ]; then echo "interpreter missing/unrunnable: $PYO3_PYTHON"; fi
"${PYO3_PYTHON:-python3}" -c 'print("ok")' || echo 'interpreter cannot execute'

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of PyO3/pyo3@ac9b6899d3 (2026-09-05). Data as JSON: /api/errors/46b50a8329b7b6ff. Report an issue: GitHub.