Skip to main content

abi3t-doctor

Answer one question: does my dependency tree actually run on free-threaded Python 3.15?

Python 3.15 adds abi3t, a Stable ABI for free-threaded builds (PEP 803). The migration it enables is blocked in a specific, checkable way, and it is not the way most people expect:

A free-threaded interpreter's EXTENSION_SUFFIXES is ['.cpython-315t-....so', '.abi3t.so', '.so'] — there is no .abi3.so entry.

So an abi3 wheel is not "slower on 3.15t" or "untested on 3.15t". It is not loaded at all. Every compiled dependency in your tree needs an abi3t build, a version-specific cp315t build, or no compiled code.

abi3t-doctor checks that from wheel tags, and — where the tags are not to be trusted — from the symbol tables of the binaries underneath them.

$ abi3t-doctor env
target: cp315t  (Python 3.15, free-threaded)

  needs-rebuild            cryptography 41.0.7
      error D410 _rust.abi3.so is an abi3 extension, which a free-threaded build will not load
        A free-threaded interpreter's EXTENSION_SUFFIXES omits '.abi3.so'. The project
        needs an abi3t or cp3XXt build.
  needs-rebuild            PyYAML 6.0.1
      error D411 _yaml.cpython-312-x86_64-linux-gnu.so is built for cp312, not cp315t

23 distribution(s) checked
  needs-rebuild            4
  pure                     19

4 distribution(s) block cp315t: charset_normalizer, cryptography, markupsafe, PyYAML

Existing tooling does not cover this. abi3audit audits the old abi3 and predates abi3t entirely; installers report tag mismatches one package at a time, at install time, after you have already committed to the upgrade.

Install

$ pip install abi3t-doctor

No dependencies, and no readelf, nm, otool or dumpbin either — the ELF, Mach-O and PE readers are pure Python, so a Linux CI runner can inspect a Windows .pyd without a toolchain. Runs on Python 3.9+; you do not need a 3.15 build to ask about 3.15.

The four commands

$ abi3t-doctor env                       # will what I have installed work?
$ abi3t-doctor tree requirements.txt     # will what I depend on work?
$ abi3t-doctor wheel dist/*.whl          # does the wheel I built hold up?
$ abi3t-doctor tags <filename>           # what does this tag actually mean?

The target defaults to free-threaded 3.15. --target 3.14t, --target 3.15 and so on move it, which is how you find out whether the blocker is your code or the calendar.

env

Diagnoses what is on disk. This is the most trustworthy check available, because the extension modules it reads are the exact binaries that would be loaded — no guessing which wheel an installer would pick. Metadata comes from .dist-info directories rather than importlib.metadata, so a distribution whose imports are broken is still described rather than raising.

tree

Asks the index what a project publishes, before you install anything:

$ abi3t-doctor tree requirements.txt
target: cp315t  (Python 3.15, free-threaded)

  source-only              cryptography 50.0.1
      warning D424 cryptography ships free-threaded wheels (cp314t) but none for cp315t
        Free-threading support exists upstream; this is a release-cadence gap, not a
        porting problem. An abi3t build would close it permanently.

5 distribution(s) checked
  source-only              3
  ready                    1
  pure                     1

That distinction matters. "Ships cp314t but not cp315t yet" is a very different conversation with upstream than "no free-threading support at all", and flattening both into source-only would hide it.

Responses are cached for a day; --offline uses only the cache. --deep downloads a candidate wheel per distribution and runs the symbol checks on it.

wheel

For the other side of the problem — you are the one shipping the wheel:

$ abi3t-doctor wheel dist/*.whl
mypkg-1.0-cp315-abi3.abi3t-manylinux_2_17_x86_64.whl
  tags: cp315-abi3-manylinux_2_17_x86_64, cp315-abi3t-manylinux_2_17_x86_64
  mypkg/_speed.abi3.so  elf/64 x86_64 abi=abi3 hook=PyInit__speed imports=87
  error F301 wheel is tagged abi3t but this file is named '.abi3.so', which a
             free-threaded build never searches for
  error S203 exports PyInit__speed() but abi3t requires PEP 793's PyModExport_ hook
  error S205 imports 3 symbol(s) outside the Stable ABI, so the abi3 tag does not
             hold: PyUnicode_AsUTF8, PyFrame_GetBack, PyEval_GetFrame

Exit code 1 on any error, so it drops into a release pipeline as a gate.

tags

The quick one, for when a filename is confusing:

$ abi3t-doctor tags pkg-1.0-cp315-abi3.abi3t-win_amd64.whl
pkg 1.0
  no cp315-abi3-win_amd64      abi3     abi3-on-free-threaded
  ok cp315-abi3t-win_amd64     abi3t    compatible

What it checks

Tags (T1xx) — the filename's claim. Compressed tag sets are expanded the way an installer expands them, so cp315.cp316-abi3.abi3t becomes four tags and each is judged on its own. abi3t below 3.15 is an error; PEP 803 does not define it.

Symbols (S2xx) — what the binary actually needs, read from its symbol table and compared against CPython's own Misc/stable_abi.toml (967 symbols, with the version each was added):

  • A symbol outside the Stable ABI in a wheel tagged abi3. The tag does not hold; the wheel works on the version it was built against and fails elsewhere.
  • A Stable ABI symbol newer than the wheel's cp3XX tag. cp39-abi3 importing PyList_GetItemRef (stable since 3.13) fails on 3.9 through 3.12 — the interpreters the tag exists to promise.
  • An exported PyInit_ hook on an abi3t wheel. PEP 803 requires PEP 793's PyModExport_, because PyModuleDef is opaque under abi3t and a PyInit_ function has to return one. An exported PyInit_ is proof the wheel was not built for abi3t, whatever its tag says.
  • A symbol abi3t makes unusable — PyModuleDef_Init, PyModule_Create2, PyType_GetModuleByDef and friends, all of which take or return that now-opaque struct. Use PyModule_GetToken() and PyType_GetModuleByToken() instead.
  • A GIL-specific symbol such as PyEval_InitThreads, removed in 3.13.

File layout (F3xx) — whether the import system will even look for the file. A wheel tagged abi3.abi3t that ships only foo.abi3.so installs cleanly and then fails to import, which is the most confusing of the three failure modes.

Distributions (D4xx) — whether anything installable exists at all, and whether a source build could produce it. As the 3.15 release notes say outright, the mainstream build backends were still catching up on abi3t at release, so a project needing one may be blocked on its toolchain rather than on its own code.

Codes are stable and grouped by prefix so you can reason about a class of finding at a time.

Verdicts

verdict meaning blocks?
pure No compiled code; runs anywhere. no
ready A compatible binary exists and holds up to inspection. no
source-only No wheel; installing means compiling. no
unknown Not enough information to say. no
mistagged A binary claims an ABI its symbols contradict. yes
needs-rebuild Compiled, but not for this interpreter. yes
unavailable Nothing published that could work. yes

In CI

- run: pip install abi3t-doctor
- run: abi3t-doctor env --target 3.15t          # fails on a blocker
- run: abi3t-doctor wheel dist/*.whl            # fails on a mistagged wheel
- run: abi3t-doctor tree --format json > abi3t.json

Library use

from pathlib import Path
from abi3t_doctor import Target, inspect_wheel, read_symbols_from_path

report = inspect_wheel(Path("dist/pkg-1.0-cp315-abi3.abi3t-win_amd64.whl"))
for finding in report.findings:
    print(finding)

table = read_symbols_from_path(Path("pkg/_speed.abi3t.so"))
print(table.format, table.arch, len(table.imported))

abi3t_doctor.tags for tag arithmetic, abi3t_doctor.binary for the symbol readers, abi3t_doctor.stable_abi for the manifest and the abi3t restrictions, abi3t_doctor.diagnose for the verdicts.

Limitations

  • A wheel's tags and symbols are checked; whether the code inside is actually thread-safe is not something a symbol table can tell you. abi3t-doctor says a wheel will load, not that it is correct under free threading.
  • Platform tag matching is exact. --platform filters by tag string; there is no manylinux/macOS version-compatibility ladder yet, so the default accepts any platform.
  • Statically linked, stripped or packed binaries yield no symbols. Those are reported as unread rather than as clean.
  • Build-backend abi3t support is a fast-moving target; treat the backend notes as a pointer to check the backend's own docs, not as current fact.
  • The dependency tree is read from requirement files or the installed environment. There is no resolver — transitive dependencies show up only if they are installed or listed.

Licence

0BSD -- public-domain-equivalent. Use it for anything, with no attribution required.

Metadata

Release files for abi3t-doctor 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for abi3t-doctor 0.1.0
File Size Uploaded Provenance Actions
abi3t_doctor-0.1.0.tar.gz 57.7 kB Without provenance Details for abi3t_doctor-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for abi3t-doctor 0.1.0
File Interpreter ABI Platform Actions
abi3t_doctor-0.1.0-py3-none-any.whl Python 3 none any Details for abi3t_doctor-0.1.0-py3-none-any.whl

Total release size: 110.7 kB

Release files / abi3t_doctor-0.1.0.tar.gz

Download URL abi3t_doctor-0.1.0.tar.gz
Size 57.7 kB
Tags Source
SHA-256 checksum
How to use checksums
153bb6c2fea6564686c7a88249e9f8ff432bb4d22f3c8d9887a12ceccba787d9
BLAKE2b-256 checksum
How to use checksums
187aabfd89997a12ec3a0ea6f631f3026b73cc3412772b7966527b469c526f83
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / abi3t_doctor-0.1.0-py3-none-any.whl

Download URL abi3t_doctor-0.1.0-py3-none-any.whl
Size 53.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fe2cd36a454b9c6a991a957ff415ce8c33b726657a2629413837594054382f09
BLAKE2b-256 checksum
How to use checksums
25e266509324c975290253b611adf486227fd8283400be357d25716391895d53
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for abi3t-doctor 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page