cannot set a minimum Python version {} higher than the inter

Error message

cannot set a minimum Python version {} higher than the interpreter version {} (the minimum Python version is implied by the abi3-py3{} feature)

What it means

When the stable ABI is in play, the abi3-py3XX feature implies a minimum supported Python version. sanitize_stable_abi_version rejects a configuration where that implied minimum exceeds the actual interpreter version being built against, because an abi3 extension cannot require a newer Python than the interpreter it links to.

Source

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

    env::var_os(var)
}

/// Gets the compilation target triple from environment variables set by Cargo.
///
/// Must be called from a crate build script.
pub fn target_triple_from_env() -> Triple {
    env::var("TARGET")
        .expect("target_triple_from_env() must be called from a build script")
        .parse()
        .expect("Unrecognized TARGET environment variable value")
}

fn sanitize_stable_abi_version(
    stable_abi_version: Option<PythonVersion>,
    version: PythonVersion,
) -> Result<PythonVersion> {
    if let Some(min_version) = stable_abi_version {
        ensure!(
            min_version <= version,
            "cannot set a minimum Python version {} higher than the interpreter version {} \
             (the minimum Python version is implied by the abi3-py3{} feature)",
            min_version,
            version,
            min_version.minor
        );
        Ok(min_version)
    } else {
        Ok(version)
    }
}

/// Selects which stable ABI (kind and minimum version) from the `abi3-py3*`
/// and `abi3t-py3*` features (if any) applies to the given interpreter.
///
/// Interpreters which cannot target the requested stable ABI (e.g.
/// free-threaded CPython before 3.15) get a version-specific build instead.

View on GitHub (pinned to ac9b6899d3)

Solutions

Lower the abi3 feature to abi3-py3XX where XX <= your interpreter's minor version, or drop abi3 features entirely
Upgrade the Python interpreter you build against to at least the abi3 minimum
Find which dependency enables the higher abi3-pyXXX feature (`cargo tree -e features`) and align versions across the workspace

Example fix

// before (python3.9 on PATH)
pyo3 = { version = "0.22", features = ["abi3-py312"] }
// after
pyo3 = { version = "0.22", features = ["abi3-py39"] }

Defensive patterns

Strategy: validation

Validate before calling

// shell
PY=${PYO3_PYTHON:-python3}; MAJ=$($PY -c 'import sys;print(sys.version_info[0])'); MIN=$($PY -c 'import sys;print(sys.version_info[1])'); echo "interpreter $MAJ.$MIN — ensure abi3-py3${MIN} feature <= this"

Prevention

Keep the abi3-py3XX feature at or below the lowest interpreter in your CI matrix
Check cargo tree -e features for abi3-pyXXX leaking in from dependencies
Document the required minimum Python next to the feature declaration

When it happens

Trigger: Building against, say, a 3.9 interpreter while the feature set includes abi3-py310 or higher (or a config file / PYO3_CCONFIG declares abi3 version 3.10+); PythonAbiBuilder calls sanitize_stable_abi_version(stable_abi_version, version) and ensure!(min_version <= version) fails.

Common situations: Cargo feature unification picks up abi3-py312 from a dependency while your local interpreter is older; CI matrix installs an older Python than the abi3-pyXXX feature declared; a PYO3_CONFIG_FILE pins an older interpreter while features demand a newer minimum.

Related errors

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