Add support for abi3audit for Stable ABI wheels and run it automatically

[agriyakhetarpal]

This PR adds support for auditing Stable ABI wheels via abi3audit. It is only a draft for now ready for initial review since there are many items to be completed (but most importantly the fourth one):

• Initial helper functions to recognise/distinguish Stable ABI wheels
• Windows and macOS support
• Linux (containers) support
• Come up with a consensus based on what has been discussed in Consider running abi3audit on abi3 wheels #1342
• Tests
  • Unit tests
  • Set up a new C extension that uses Py_LIMITED_API
• Docs (i.e., removing the abi3audit suggestion and mentioning we do it automatically)

One follow-up will be to test a C extension with free-threaded Python 3.15. However, that will be for later, since we don't know yet what the knobs will look like to enable both. PEP 803 is still in draft, and this is being discussed there.

Closes #1342

cc: @ngoldbaum, since you requested this feature over in the PyPA Discord server 👾

[agriyakhetarpal]

Ready for initial review!

[Copilot]

Pull request overview

This PR adds automatic support for auditing Stable ABI (abi3) wheels using the abi3audit tool. When cibuildwheel builds a wheel that uses the Python Limited API (tagged as abi3), it now automatically runs abi3audit to verify that the wheel doesn't violate the stable ABI contract. This helps catch issues where C extensions claim to use the stable ABI but actually use functions that aren't part of it.

Changes:

• Added abi3audit as a dependency and integrated automatic execution after the wheel repair step
• Implemented helper functions to detect abi3 wheels and run abi3audit with appropriate flags
• Added comprehensive unit and integration tests including a test project that intentionally violates the stable ABI
• Updated documentation to reflect that abi3audit is now run automatically

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cibuildwheel/util/packaging.py	Added is_abi3_wheel() to detect abi3 wheels and run_abi3audit() to execute the audit tool
cibuildwheel/platforms/windows.py	Integrated abi3audit call after wheel repair step
cibuildwheel/platforms/macos.py	Integrated abi3audit call after wheel repair step
cibuildwheel/platforms/linux.py	Integrated abi3audit with special handling to copy wheel out of container before auditing
unit_test/abi3audit_test.py	Added unit tests for wheel detection and abi3audit execution
test/test_abi3audit.py	Added integration tests with valid and invalid abi3 projects
pyproject.toml	Added abi3audit as a project dependency
docs/options.md	Removed manual abi3audit examples and added note about automatic execution
docs/faq.md	Updated to mention automatic abi3audit execution

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Consider adding a minimum version constraint for abi3audit to ensure the --strict and --report flags are available. For example, abi3audit>=0.0.8 would ensure compatibility with the flags used in the code. This would prevent issues if someone has an older version of abi3audit installed in their environment.

Suggested change

	"abi3audit",
	"abi3audit>=0.0.8",

[agriyakhetarpal]

https://github.com/pypa/abi3audit/releases/tag/v0.0.26 lists Python 3.10 as the minimum supported version. There's no proper CHANGELOG for older versions (such as v0.0.8, as suggested here), so I'm not sure when the --strict flag was added.

But this begs the question: what's the best approach for us here? We wouldn't want to run different versions of abi3audit without the user knowing, right?

[agriyakhetarpal]

Ready for initial review!

Thinking a little more after Copilot's suggestion, should we wait for/implement pypa/abi3audit#111 or wait for a v1 release?

My concern, as an initial self-reviewer, is that we are going to subscribe everyone to use abi3audit for Stable ABI wheels, and if they find a bug or can't use it right now, they can't disable running it.

• Should we keep it off by default and provide flags to enable running it, or keep it on but provide flags to disable it? I lean toward the first, since abi3audit is still in v0.0.X stage and is marked as "Beta" via its trove classifier on PyPA, so I am not aware of how stable it is (no pun intended :D). I suppose it's fairly stable by now, based on this comment: Consider running abi3audit on abi3 wheels #1342 (comment), but our users will have their own stance.
• Also, note that the dependency on abi3audit is not conditional either, and I'd like suggestions on how we could change that – i.e., to somehow not pull it in unless we are building a Stable ABI wheel. This is the same question as @joerick had in Consider running abi3audit on abi3 wheels #1342 (comment). Personally, I'd even be okay if we were to keep the dependency unconditional, since it's mostly going to be harmless (outside the fact that it introduces one more dependency to our supply chain, but that's mostly fine).
• Lastly, abi3audit supports tighter versions of Python and is likely to do so going forward, as I noted in Add support for abi3audit for Stable ABI wheels and run it automatically #2745 (comment) above, as it supports 3.10 and later at the time of writing. From Consider running abi3audit on abi3 wheels #1342 (comment), Python 3.8 support was reintroduced in abi3audit around March 2023. However, it is only now, or rather (in a few months), that we are aiming to drop Python 3.8 support (Drop Python 3.8 #2685, break: drop Python 3.8 #2686). Our Python version support is influenced by that of the manylinux images, whose release cycles, if I understand correctly, abi3audit does not comply with at this time.

In light of these points, I would suggest we could ask the abi3audit maintainers for their opinion (again, that is, since we are in 2026 now and times have continued to change)? I am unable to ping the abi3audit team under PyPA for some reason, so, @woodruffw, hi! 👋🏻 I see that you have been heavily involved in abi3audit's development, being its author, even before it was adopted by PyPA. May I ask you if you could chime in here? I see that you have marked yourself as busy on GitHub – there is no hurry for a response. It would be great if you could help review and answer these questions whenever you have a chance. Thank you! :D

[woodruffw]

Hi @agriyakhetarpal, thanks for the ping! I'm happy to see that cibuildwheel is considering integrating abi3audit; I think they go together naturally 🙂

My concern, as an initial self-reviewer, is that we are going to subscribe everyone to use abi3audit for Stable ABI wheels, and if they find a bug or can't use it right now, they can't disable running it.

This seems like a fair concern; I think it'd be very reasonable to enable it by default, but have a well-documented flag to disable abi3audit for users who run into issues (if any do).

since abi3audit is still in v0.0.X stage and is marked as "Beta" via its trove classifier on PyPA, so I am not aware of how stable it is (no pun intended :D)

This is mostly just laziness on my part -- I think it's stable for all practical purposes. If a v0.x release and a classifier change would be helpful, I'm happy to make those changes.

Lastly, abi3audit supports tighter versions of Python and is likely to do so going forward, as I noted in #2745 (comment) above, as it supports 3.10 and later at the time of writing

In my mind, this goes together with the "unconditional dependency point" directly above it 🙂. My 0.02c:

• abi3audit can audit wheels for older (EOL) Python versions, even if it's running on a newer version of Python itself. Is it possible that cibuildwheel could run abi3audit somewhere isolated where it always has a newer (non-EOL) version of Python?
• If that's not feasible, I'm open to having abi3audit support older (EOL) Python versions. However, it's definitely not something I'd prefer to do, since older versions are increasingly hard IME to test in GitHub Actions.

Separately, I've actually been thinking about rewriting abi3audit recently (in Rust, naturally). In that case, it would have no runtime Python requirements, but it would also be a Rust binary instead of Python source (although it would still be packaged on PyPI). Would that be tractable for your integration, or would it add an additional layer of complexity? If it'd be a significant problem that would be a good reason for me to not rewrite it 🙂