Unable to build abi3 wheel for Rust bin

[gar1t]

I've enabled the abi3 feature for pyo3 per Bindings doc and pyo3's Building and distribution.

Cargo dependency config:

pyo3 = { version = "0.27.2", features = ["abi3-py310"] }

However, I have not met Step 3, "Ensure that the .whl is correctly marked as abi3". As I'm using maturin I'm assuming it would handle when it detects the feature. The step refers to setting --py-limited-api=cp3x but for setuptools. Is there something here I need to specify for maturin, beyond the abi3-py310 feature in Cargo.toml?

In the tutorial output, maturin shows:

Found pyo3 bindings with abi3 support for Python ≥ 3.8
...
Built wheel for abi3 Python ≥ 3.8 to .../target/wheels/guessing_game-0.1.0-cp37-abi3-macosx_10_7_x86_64.whl

I've only ever seen:

Found CPython 3.12 at .../.venv/bin/python
...
Built wheel to .../target/wheels/gage_cli-0.2.1.dev4-cp312-cp312-...whl

I'm seeing the same behavior on both Linux and macOS.

This is for a binary crate in Rust that calls Python::initialize().

UPDATE: I see I misread the docs. The steps above refer to extension modules. As I'm building a bin (Rust program that uses Python) these don't seem to apply in my case. I would still think it possible to create an abi3 wheel but maturin seems to not apply this config for bin bindings.

[pratyush618]

No — maturin does not produce abi3 wheels for the bin bridge model. The abi3-py3xx feature on pyo3 is silently ignored for binary projects: maturin always builds one wheel per Python interpreter with a version-specific tag, regardless of whether abi3-pyXY is enabled in Cargo.toml. This is by design of the current code path, not a bug in your config.

Where this is decided in the code

The wheel-tag logic for bin crates lives in write_bin_wheel in src/build_orchestrator.rs:

// src/build_orchestrator.rs:797-803
let tag = match (self.context.project.bridge(), python_interpreter) {
    (BridgeModel::Bin(None), _) => self.get_universal_tag(platform_tags)?,
    (BridgeModel::Bin(Some(..)), Some(python_interpreter)) => {
        python_interpreter.get_tag(&self.context.project, platform_tags)?
    }
    _ => unreachable!(),
};

For Bin(Some(..)) (a binary that links pyo3 — your case), the tag comes unconditionally from python_interpreter.get_tag(...), which yields cp3X-cp3X-<platform>. The stable_abi field on the wrapped PyO3 struct is never inspected here.

The driver that decides how many wheels to build is at src/build_orchestrator.rs:219-223:

BridgeModel::Bin(None)        => self.build_bin_wheel(None, &sbom_data)?,
BridgeModel::Bin(Some(..))    => self.build_bin_wheels(&interpreters, &sbom_data)?,   // one per interpreter
BridgeModel::PyO3(crate::PyO3 { stable_abi, .. }) => match stable_abi {
    Some(stable_abi) => self.build_stable_abi_wheels(stable_abi, &sbom_data)?,        // single abi3 wheel
    ...
}

build_bin_wheels (src/build_orchestrator.rs:908-917) loops over every found interpreter and emits a separate version-specific wheel for each. Only the BridgeModel::PyO3 branch has a build_stable_abi_wheels path that emits a single cp3X-abi3-… wheel.

There is one place — tags_from_bridge (src/build_orchestrator.rs:281-291) — that would report an abi3 tag for Bin(Some(bindings)) if bindings.stable_abi were set, but stable_abi for the Bin variant is hardcoded to None (src/build_orchestrator.rs:56) and the actual wheel-building path (write_bin_wheel) ignores it anyway. So that branch is effectively dead code for bin crates.

Why it isn't supported

This is a real semantic mismatch, not just a missing flag:

• Extension module (PyO3/cdylib): the wheel ships a .so/.pyd that Python loads at runtime. If it was compiled against Py_LIMITED_API, a single cp3X-abi3 wheel can be loaded by any CPython ≥ 3.X.
• bin crate: the wheel ships a standalone executable that calls Python::initialize() and embeds CPython itself. That executable links against a specific libpython3.X (or, on Windows, python3X.dll) at build time — its ABI compatibility is determined by the link target, not by Py_LIMITED_API / python3.dll. Even with abi3-py310 set on pyo3, the binary is still bound to the libpython it was linked against, so a "universal" abi3 wheel for an embedded interpreter wouldn't be meaningful in the way it is for an extension module.

So there isn't a quick "just emit the abi3 tag for bin too" fix — making this work would require maturin's bin path to either (a) link against the limited-API stub library (python3.dll / libpython3.so) on platforms that have one and refuse where it doesn't, or (b) declare abi3 for bin to mean "the Python entry-point wrapper is abi3, the binary is launched out-of-process per-interpreter," which is a different shape of artifact.

What you can actually do today

1. Drop the abi3-py310 feature for the bin crate. It is doing nothing for you and only hides the fact that the binary is locked to a specific CPython.
2. Build one wheel per CPython version you want to support. Either point maturin build at multiple interpreters in turn, or use maturin build --interpreter python3.10 python3.11 python3.12 … / the PyO3 manylinux Docker image to produce the matrix. The resulting wheels will be tagged cp310-cp310-…, cp311-cp311-…, etc.
3. If your goal is "one wheel that runs on any Python 3.10+", the bin bridge is the wrong tool — the embedded interpreter forces version-specific artifacts. If you can restructure the project as a CPython extension module plus a tiny console-script entry point, the PyO3 (cdylib) path will produce a single cp310-abi3 wheel for you.

Bottom line

Your config is fine; you have not missed a flag. maturin currently builds version-specific wheels for any bin project that uses pyo3, because an embedded-interpreter executable is not abi3 in the same sense an extension module is. If you want a single wheel across CPython versions, switch the crate to a cdylib extension module — the existing abi3-py310 feature will then take effect and you will get the cp310-abi3 tag you were expecting.

---

References (file:line)

• src/build_orchestrator.rs:219-223 — bin vs PyO3 wheel-build dispatch
• src/build_orchestrator.rs:278-317 — tags_from_bridge (theoretical abi3 reporting for Bin(Some(..)), never reached)
• src/build_orchestrator.rs:56 — stable_abi: None for the Bin PyO3 wrapper
• src/build_orchestrator.rs:797-803 — actual tag selection in write_bin_wheel
• src/build_orchestrator.rs:854-901 — build_bin_wheel always returns a "py3"/version-specific tag
• src/build_orchestrator.rs:908-917 — build_bin_wheels loops one wheel per interpreter
• src/bridge/mod.rs:264-273 — BridgeModel::Bin(Option<PyO3>) definition