the configured Python interpreter version ({}) is lower than

Error message

the configured Python interpreter version ({}) is lower than PyO3's minimum supported version ({})

What it means

pyo3-ffi's build script refuses to compile when the detected CPython interpreter version is older than the minimum supported by this PyO3 release. This is a compile-time guard: PyO3's FFI bindings rely on APIs absent in older CPython.

Source

Thrown at pyo3-ffi/build.rs:62

};

const PY_3_15: PythonVersion = PythonVersion {
    major: 3,
    minor: 15,
};

fn ensure_python_version(interpreter_config: &InterpreterConfig) -> Result<()> {
    // This is an undocumented env var which is only really intended to be used in CI / for testing
    // and development.
    if std::env::var("UNSAFE_PYO3_SKIP_VERSION_CHECK").as_deref() == Ok("1") {
        return Ok(());
    }

    match interpreter_config.target_abi().implementation() {
        PythonImplementation::CPython => {
            let versions = SUPPORTED_VERSIONS_CPYTHON;
            let interp_version = interpreter_config.target_abi().version();
            ensure!(
                interpreter_config.version() >= versions.min,
                "the configured Python interpreter version ({}) is lower than PyO3's minimum supported version ({})",
                interpreter_config.version(),
                versions.min,
            );
            let v_plus_1 = PythonVersion {
                major: versions.max.major,
                minor: versions.max.minor + 1,
            };
            if interp_version == v_plus_1 {
                warn!(
                    "Using experimental support for the Python {}.{} ABI. \
                     Build artifacts may not be compatible with the final release of CPython, \
                     so do not distribute them.",
                    v_plus_1.major, v_plus_1.minor,
                );
            } else if interp_version > v_plus_1 {
                let mut error = MaximumVersionExceeded::new(interpreter_config, versions.max);

View on GitHub (pinned to ac9b6899d3)

Solutions

Install and select a newer CPython (e.g. 3.11+) and rebuild
Point the build at the right interpreter: export PYO3_PYTHON=/path/to/python3.12
Check the resolved version with python --version and rustc-linked pyo3-build-config output
If the old interpreter is intentional, downgrade pyo3 to a release that supports it
In CI, cache/preinstall the required Python version

Example fix

// before (Cargo.toml)
pyo3 = "0.22"   # with python3.7 on PATH
// after: install python3.11 and run
PYO3_PYTHON=$(which python3.11) cargo build

Defensive patterns

Strategy: validation

Validate before calling

import sys
MIN = (3, 7)  # check your pyo3 version's SUPPORTED_VERSIONS_CPYTHON
v = sys.version_info[:2]
assert v >= MIN, f"CPython {v} too old for this pyo3; need >= {MIN}"

Prevention

Check pyo3's release notes for its supported CPython range before upgrading
Pin the Python version in CI (actions/setup-python or pyenv) to match pyo3's minimum
Set PYO3_PYTHON explicitly rather than relying on PATH resolution
Add a pre-build script that asserts the interpreter version

When it happens

Trigger: Building a crate that depends on pyo3/pyo3-ffi against a CPython interpreter (via PYO3_PYTHON, pyenv, system python) whose major.minor version is below SUPPORTED_VERSIONS_CPYTHON.min for the crate's PyO3 version.

Common situations: Old system Python (e.g. 3.6/3.7) picked up automatically; distro EOL Python; CI images with outdated Python; upgrading pyo3 in Cargo.toml while the interpreter stays old.

Related errors

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