your Rust target architecture ({}-bit) does not match your p

Error message

your Rust target architecture ({}-bit) does not match your python interpreter ({}-bit)

What it means

The build script compares the Rust target's pointer width with the pointer width reported by the Python interpreter configuration and aborts on mismatch, since a pyo3 extension module must be compiled for the same word size as the interpreter.

Source

Thrown at pyo3-ffi/build.rs:184

        }
    }

    Ok(())
}

fn ensure_target_pointer_width(interpreter_config: &InterpreterConfig) -> Result<()> {
    if let Some(pointer_width) = interpreter_config.pointer_width() {
        // Try to check whether the target architecture matches the python library
        let rust_target = match cargo_env_var("CARGO_CFG_TARGET_POINTER_WIDTH")
            .unwrap()
            .as_str()
        {
            "64" => 64,
            "32" => 32,
            x => bail!("unexpected Rust target pointer width: {}", x),
        };

        ensure!(
            rust_target == pointer_width,
            "your Rust target architecture ({}-bit) does not match your python interpreter ({}-bit)",
            rust_target,
            pointer_width
        );
    }
    Ok(())
}

/// `raw-dylib` currently does not support arbitrary names
/// (see https://internals.rust-lang.org/t/support-renames-with-link-name-kind-raw-dylib/24415)
/// so if the lib name is not one of the known subset, we must fall back to full linking.
fn lib_name_is_known_for_raw_dylib(lib_name: &str) -> bool {
    // pyo3_dll cfg for raw-dylib linking on Windows
    if matches!(
        lib_name,
        "python3" | "python3_d" | "python3t" | "python3t_d"
    ) {

View on GitHub (pinned to ac9b6899d3)

Solutions

Use a Python interpreter matching the Rust target's pointer width (e.g. 32-bit Python for a 32-bit target)
Set PYO3_CROSS / PYO3_CROSS_PYTHON_VERSION and PYO3_CROSS_PYTHON_IMPLEMENTATION for cross builds instead of pointing at host Python
Change the Rust target (rustup target) to match the Python bitness
Verify with python -c "import struct; print(struct.calcsize('P')*8)" and rustc --print target-pointer-width

Example fix

// before
cargo build --target i686-unknown-linux-gnu   # using 64-bit python3
// after
PYO3_CROSS_PYTHON_VERSION=3.12 cargo build --target i686-unknown-linux-gnu
# or use a 32-bit python interpreter

Defensive patterns

Strategy: validation

Validate before calling

import struct, os, subprocess
def python_bits(): return struct.calcsize("P") * 8
def rust_target_bits(target):
    return 64 if "64" in target or "aarch64" in target or "x86_64" in target else 32
# assert python_bits() == rust_target_bits(os.environ.get("CARGO_BUILD_TARGET", "x86_64"))

Prevention

In cross-compilation, always set PYO3_CROSS_PYTHON_VERSION / PYO3_CROSS_PYTHON_IMPLEMENTATION instead of relying on host Python
Use maturin/cibuildwheel which manage matching interpreters per target
Verify pointer widths before starting cross builds
Keep separate 32-bit Python installs for 32-bit targets

When it happens

Trigger: Cross-compiling with a Rust target whose pointer width differs from the configured Python (e.g. building for i686/aarch32 Rust target against 64-bit Python, or vice versa), inside ensure_target_pointer_width.

Common situations: Cross-compiling wheels for 32-bit platforms using the host's 64-bit Python; mixed 32/64-bit Python installs on Windows; wrong CC/PYTHON targets in CI cross jobs.

Related errors

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