ImportError: Numba needs NumPy 1.26 or less

TL;DR: your numba is too old for your numpy. Numba only learned numpy 2 support in later releases. Upgrade numba, or downgrade numpy to 1.26.x.

The error

ImportError: Numba needs NumPy 1.26 or less

Fix it

1. Upgrade numba to a numpy-2-compatible release:

   pip install -U numba

   Expected: installs numba new enough for numpy 2.

2. Verify:

   python -c "import numba, numpy; print(numba.__version__, numpy.__version__)"

   Expected: both import, no error.

3. If you cannot upgrade numba (other pins), downgrade numpy instead:

   pip install "numpy<1.27"

   Expected: the version check passes.

When this applies

Use this when import numba raises this exact message and numpy 2.x is installed.

When it does not apply

If the error is a different numpy/numba complaint, check the versions individually. If numba is already current, reinstall it; the install may be corrupt.

Compatibility

numba below 0.59 with numpy 2.x. numba 0.59+ supports numpy 2.

Root cause

numba inspects the numpy version at import and refuses numpy 2 in releases built before numpy 2 support landed. The guard is deliberate: the old compiled code is not binary-compatible with numpy 2.

Edge cases

llvmlite must be upgraded in lockstep with numba; pip handles this if you upgrade numba normally. Downgrading numpy can break packages that require numpy 2, so upgrading numba is the better direction.

GitHub issue py-econometrics/pyfixest#1248 reports ImportError: Numba needs NumPy 1.26 or less when importing numba with numpy 2.x installed. The verified resolution: the installed numba release predates numpy 2 support, so the fix is upgrading numba to a release that supports numpy 2, or downgrading numpy to 1.26.x as a stopgap. Full thread: https://github.com/py-econometrics/pyfixest/issues/1248