PyO3/pyo3 · error

Python script failed

Error message

Python script failed

What it means

pyo3 probes the Python interpreter by piping an inspection script and checking the exit status. If the interpreter runs but exits with a non-zero status, the build fails with the terse message 'Python script failed'. The interpreter's stderr is surfaced by cargo, so the real cause is usually printed just above this error.

Source

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

        .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 {
        venv.join("Scripts").join("python.exe")
    } else {
        venv.join("bin").join("python")
    }
}

View on GitHub (pinned to ac9b6899d3)

Solutions

1. Run the failing interpreter manually and reproduce: `<path> -c "import sysconfig; print(sysconfig.get_config_var('EXT_SUFFIX'))"` to see the real error
2. Point PYO3_PYTHON at a known-good interpreter and rebuild
3. Reinstall or repair the broken Python installation
4. Check the interpreter's stderr output printed above the error by cargo for the root cause

Example fix

// shell, before
export PYO3_PYTHON=/mnt/broken/python  # crashes on start
// after
export PYO3_PYTHON=$(which python3) && cargo build

// shell
${PYO3_PYTHON:-python3} -c 'import sys, sysconfig; print(sys.version); print(sysconfig.get_config_var("EXT_SUFFIX"))' >/dev/null || echo 'probe fails: interpreter broken; see its stderr'

When it happens

Trigger: run_python_script's child process returns Ok(output) with !output.status.success() — i.e. the interpreter started but the probe script (importing sys, reading sysconfig vars like EXT_SUFFIX / Py_GIL_DISABLED) crashed or the interpreter aborted.

Common situations: A broken/incompatible interpreter that crashes on startup (partially installed Python, conflicting site-packages, missing DLLs on Windows); a wrapper script that exits non-zero; GraalPy/PyPy builds that fail importing required modules; wrong interpreter architecture for the OS.

Related errors

• failed to run the Python interpreter at {}: {}
• broken Python interpreter: {}
• Neither abi3 or abi3t features are enabled
• Cannot target an abi3t version below {MINIMUM_SUPPORTED_VERS
• cannot set a minimum Python version {} higher than the inter

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