{"id":7892,"library":"abi3audit","title":"abi3audit: Python ABI3 Compliance Auditor","description":"abi3audit is a command-line tool developed by Trail of Bits and now maintained by the Python Packaging Authority (PyPA). It scans Python wheels and shared objects for Application Binary Interface (ABI) violations and inconsistencies. Its purpose is to ensure that CPython extensions tagged as `abi3` actually comply with the stable ABI, thereby preventing potential crashes or memory corruption due to ABI mismatches. The library is currently at version 0.0.26 and receives frequent, minor releases, indicating active development.","status":"active","version":"0.0.26","language":"en","source_language":"en","source_url":"https://github.com/pypa/abi3audit","tags":["abi3","python","wheel","audit","pypi","pypa","compliance","c-extension","cli"],"install":[{"cmd":"pip install abi3audit","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"abi3audit is primarily a command-line tool. While it has an internal Python API, direct programmatic imports like `from abi3audit import ...` are not the typical or officially supported way to interact with it for auditing tasks. It's best used by invoking its CLI via `subprocess`.","symbol":"abi3audit CLI","correct":"import subprocess\nsubprocess.run(['abi3audit', 'package_name'], check=True)"}],"quickstart":{"code":"import subprocess\n\n# Audit a specific PyPI package for ABI3 compliance\n# Replace 'numpy' with the actual package name you wish to audit.\n# The '--verbose' flag provides detailed output.\npackage_to_audit = 'numpy'\n\ntry:\n    print(f\"Auditing {package_to_audit} for ABI3 compliance...\")\n    result = subprocess.run(\n        ['abi3audit', package_to_audit, '--verbose'],\n        capture_output=True,\n        text=True,\n        check=True\n    )\n    print(\"\\nAudit Successful:\\n\")\n    print(result.stdout)\nexcept subprocess.CalledProcessError as e:\n    print(f\"\\nAudit Failed for {package_to_audit}:\\n\")\n    print(f\"Stderr: {e.stderr}\")\n    print(f\"Stdout: {e.stdout}\")\nexcept FileNotFoundError:\n    print(\"Error: 'abi3audit' command not found. Is it installed and in your PATH?\")","lang":"python","description":"This quickstart demonstrates how to programmatically audit a PyPI package for ABI3 compliance using `abi3audit` via a subprocess call. The example audits 'numpy' and uses the `--verbose` flag for detailed output. It handles potential errors like `abi3audit` not being found or an audit failing."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or a later supported version (e.g., Python 3.11, 3.12, 3.13, 3.14). If Python 3.9 is required, you must use an older version of abi3audit, such as 0.0.25, and pin its version accordingly.","message":"Starting with version 0.0.26, abi3audit officially drops support for Python 3.9. Ensure your environment uses Python 3.10 or newer.","severity":"breaking","affected_versions":">=0.0.26"},{"fix":"Always check the `requires_python` metadata and the release notes for abi3audit. For stability, explicitly pin the abi3audit version in your project (e.g., `abi3audit==0.0.25`) if you depend on a specific Python version that has had fluctuating support.","message":"The support for Python 3.9 has fluctuated. It was re-added in v0.0.25 but then dropped again in v0.0.26. This can lead to unexpected compatibility issues if you rely on specific minor versions.","severity":"gotcha","affected_versions":"0.0.25, 0.0.26"},{"fix":"Whenever possible, audit entire wheels or PyPI packages (e.g., `abi3audit my_package.whl` or `abi3audit my-package`) rather than individual shared objects, as wheels contain the necessary metadata for accurate analysis.","message":"When auditing bare `.abi3.so` shared objects, abi3audit cannot infer the intended minimum ABI3 version and defaults to the lowest known version (abi3-cp32). This might result in false positives for symbols stabilized in later Python versions.","severity":"gotcha","affected_versions":"All"},{"fix":"Be aware of this limitation and combine `abi3audit` with other dynamic analysis tools if your C extensions utilize dynamic symbol loading.","message":"abi3audit is a best-effort tool and cannot detect dynamic ABI3 violations (e.g., C extensions calling `dlsym(3)` to invoke non-abi3 functions at runtime).","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade your Python environment to 3.9 or newer, or use an older version of abi3audit if Python 3.8 support is critical.","message":"Python 3.8 support was removed in version 0.0.18.","severity":"breaking","affected_versions":">=0.0.18"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `abi3audit` is installed via `pip install abi3audit` in the active Python environment. If using a virtual environment, ensure it is activated. Verify the executable's location and confirm your PATH includes the directory where pip installs scripts.","cause":"The `abi3audit` executable is not in your system's PATH, or the package was not installed correctly.","error":"abi3audit: command not found"},{"fix":"Provide a target for the audit. For example, `abi3audit my-package-name`, `abi3audit my_package.whl`, or `abi3audit my_module.abi3.so`.","cause":"The `abi3audit` command was called without specifying a target (e.g., package name, wheel file, or shared object).","error":"Error: the following arguments are required: TARGET"},{"fix":"Activate a Python environment with version 3.10 or newer, or upgrade your Python installation. Uninstall and reinstall abi3audit in the correct environment.","cause":"The Python interpreter being used to run abi3audit (or from which it was installed) is an unsupported version.","error":"Unsupported Python version: You are running Python X.Y, but abi3audit requires >=3.10"},{"fix":"Double-check the package name for typos or confirm its presence on PyPI. If it's a local file, ensure the path is correct.","cause":"The specified package name does not exist on PyPI or is misspelled.","error":"Could not find package 'nonexistent-package' on PyPI"},{"fix":"This is often not an error with `abi3audit` itself, but an informational message. The package might not use the stable ABI, or its ABI3 wheels might not be discoverable under current criteria. Consider auditing a local wheel file if you suspect an ABI3 wheel exists but isn't found.","cause":"The specified package exists, but it does not publish any wheels explicitly tagged as `abi3` on PyPI for the Python versions abi3audit checks by default.","error":"No ABI3 wheels found for package 'some-package'"}]}