torch-abi-audit¶

A small tool to audit compiled Python extension modules for compliance with the PyTorch Stable ABI (PyTorch 2.9+) — the aoti_torch_* C shim plus torch::stable::* / torch::headeronly::* C++ wrappers that let custom PyTorch extensions survive PyTorch upgrades.

As a side benefit, the same symbol-table walk also reports compliance with the CPython Stable ABI (PEP 384) — the "limited API" that lets a single wheel work across CPython versions.

Status of the PyTorch ecosystem¶

A snapshot of where things stand as of September 2026. This is not an exhaustive list, and more projects are being ported all the time, so it may be out of date by the time you read it.

Migrated (a fully stable-ABI release, measured with this tool):

• amd-quark (stable from 0.12; legacy pybind11 kept as fallback)
• torchaudio (stable from 2.10.0)
• torchcodec (stable from 0.12.0)
• torchvision (stable from 0.29.0)
• xformers (stable from 0.0.34)

In progress (adopting stable shims, not yet fully stable):

• causal-conv1d (migration PR #123 open)
• flash-attn (FA-3/Hopper only; main package still unstable)
• kvcached (PR #497 landed in main, not yet released)
• mamba-ssm (migration PR #1042 open)
• torchao (partial; first stable modules in 0.16.0, CPU kernels still unstable)
• vLLM (building a parallel stable-ABI extension _C_stable_libtorch alongside the legacy one)
• zentorch

Gaps in the stable surface still get filled in as downstream projects hit them, so the list of "completed" packages will keep growing.

Resources¶

• PyTorch docs — LibTorch Stable ABI (canonical reference, three-layer breakdown).
• PyTorch Conference Europe 2026 — How to write C++ extensions in 2026, Jane Xu & Mikayla Gawarecki (Meta): schedule entry · slides (PDF)
• Plans — LibTorch ABI Stable Plans 2026 on dev-discuss.

Why¶

CPython's stable-ABI ecosystem has abi3audit for compliance checking. The PyTorch side is brand new and there's no equivalent yet — this fills that gap, and handles both checks in one pass.

Install¶

pip install torch-abi-audit

Linux and macOS only. Windows support requires a dumpbin-based backend that isn't implemented yet.

Quick tour¶

# Inspect a single installed package by import name
torch-abi-audit torchaudio

# Or by path to its install directory or a single .so
torch-abi-audit /path/to/site-packages/torchaudio

# Whole-environment scan (active interpreter)
torch-abi-audit --env

# Specific site-packages directory + JSON
torch-abi-audit --site-packages /opt/venv/lib/python3.12/site-packages --json

The verdict types come straight from the symbol table: a torch-using library is reported as STABLE only if it links exclusively against the documented stable surface, and as UNSTABLE if any c10::*, at::*, or non-stable torch::* symbol is referenced.

How it works¶

1. Walk the target directory and collect every .so / .pyd / .dylib. Bucket each by whether it defines a PyInit_* symbol — Python extension modules go under extensions, internal bundled libraries (e.g. torch/lib/libtorch_python.so, or torchaudio's stable plugins loaded via STABLE_TORCH_LIBRARY) go under bundled_libs. Both buckets count toward the PyTorch verdict; only extensions count toward the CPython ABI verdict.
2. Run nm -uD (Linux) or nm -u (macOS) to extract undefined symbols.
3. Demangle C++ names via pycxxfilt.
4. Classify each symbol against two rule sets — the CPython stable-ABI symbol set from abi3info and the PyTorch stable namespace regexes.
5. Roll up per-library verdicts to a per-package and per-environment view.