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 May 2026. These are illustrative examples — not an exhaustive list — and more projects are being ported all the time, so this may be out of date by the time you read it.

Migration completed:

• torchao
• torchaudio
• FlashAttention-3
• xformers

In progress:

• torchcodec
• torchvision
• vLLM
• kvcached

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.