NumPy "RuntimeError: module compiled against API version" in CI

A compiled package was built against one NumPy C-API version, but a different (usually older) NumPy is installed at runtime. NumPy detects the mismatch and raises a RuntimeError on import.

What this error means

Importing a NumPy-dependent extension (scipy, pandas, a custom Cython module) raises RuntimeError: module compiled against API version 0xN but this version of numpy is 0xM. It appears after NumPy was up/downgraded independently of its consumers.

Python traceback

RuntimeError: module compiled against API version 0x10 but this version of numpy
is 0xe . Check the section C-API incompatibility ...
ImportError: numpy.core.multiarray failed to import

Common causes

Extension built against a newer NumPy

The wheel for the dependent package was compiled against a newer NumPy C-API than the NumPy actually installed, so the API version it expects is unavailable.

Unpinned NumPy drifted at install time

Installing the scientific stack without pinning NumPy let pip resolve a NumPy incompatible with the prebuilt extensions.

How to fix it

Align NumPy with its consumers

Upgrade (or pin) NumPy so it matches the C-API the extensions were built against.

Terminal

# usually: upgrade numpy to satisfy the newer extension
pip install --upgrade numpy
# or reinstall the whole coupled set together
pip install --force-reinstall numpy scipy pandas

Pin the scientific stack as a set

Lock NumPy and its consumers to a mutually compatible combination so a future resolve can’t split them.

requirements.txt

numpy==1.26.4
scipy==1.13.1
pandas==2.2.2

How to prevent it

Pin NumPy together with every package built against it.
Use a committed lockfile so the ABI-coupled set stays consistent.
Upgrade the scientific stack as a group, not piecemeal.