ImportError: Numba needs NumPy 2.2 or less (tested)

ImportError: Numba needs NumPy 2.2 or less. Got NumPy 2.3. means your Numba is older than your NumPy. Cap NumPy (pip install "numpy<2.3") or upgrade Numba. Tested below, with the NumPy limit of each Numba release.

1. Reproduce: Numba 0.61.2 with NumPy 2.3

A Python 3.11 venv with numba==0.61.2, then numpy==2.3.5 installed in a second command (for example by another package's requirements). b1.py:

import numpy
print("numpy", numpy.__version__)
import numba
print("numba", numba.__version__)

@numba.njit
def total(a):
    s = 0.0
    for x in a:
        s += x
    return s

print(total(numpy.arange(10.0)))

Output, exit code 1 (paths shortened to /venv):

numpy 2.3.5
Traceback (most recent call last):
  File "b1.py", line 3, in <module>
    import numba
  File "/venv/lib/python3.11/site-packages/numba/__init__.py", line 59, in <module>
    _ensure_critical_deps()
  File "/venv/lib/python3.11/site-packages/numba/__init__.py", line 45, in _ensure_critical_deps
    raise ImportError(msg)
ImportError: Numba needs NumPy 2.2 or less. Got NumPy 2.3.

Numba checks the NumPy version itself at import numba and refuses to load, because its compiled code is only tested against NumPy releases up to a cap. The dependency check shows the same cap from the package metadata:

$ uv pip check
The package `numba` requires `numpy>=1.24,<2.3`, but `2.3.5` is installed

The message changes with the versions. With Numba 0.60.0 and NumPy 2.2.6 it reads "2.0 or less":

$ python b1.py   # numba 0.60.0, numpy 2.2.6
numpy 2.2.6
Traceback (most recent call last):
  File "b1.py", line 3, in <module>
    import numba
  File "/venv/lib/python3.11/site-packages/numba/__init__.py", line 59, in <module>
    _ensure_critical_deps()
  File "/venv/lib/python3.11/site-packages/numba/__init__.py", line 45, in _ensure_critical_deps
    raise ImportError(msg)
ImportError: Numba needs NumPy 2.0 or less. Got NumPy 2.2.

"Numba needs NumPy 2.0 or less", "2.2 or less", "2.3 or less" all mean the same thing: your Numba is older than your NumPy.

2. Highest NumPy each Numba release allows

From the Requires-Dist metadata on PyPI (upper bound of the numpy requirement):

NumbaNewest NumPy allowed
0.60.0NumPy 2.0
0.61.0NumPy 2.1
0.61.2NumPy 2.2
0.62.0 – 0.63.1NumPy 2.3
0.64.0 – 0.66.0NumPy 2.4
0.67.0 / 0.68.0NumPy 2.5

3. Fix: cap NumPy, or upgrade Numba

Install a NumPy at or below the version named in the error:

$ pip install "numpy<2.3"
$ python b1.py
numpy 2.2.6
numba 0.61.2
45.0

Or upgrade Numba so it supports your NumPy (here on Python 3.11 the upgrade resolved to Numba 0.68.0 with NumPy 2.4.6):

$ pip install -U numba numpy
$ python b1.py
numpy 2.4.6
numba 0.68.0
45.0

If NumPy keeps getting bumped past the cap, install both in one command (pip install numba numpy) so the resolver picks a compatible pair, and restart any Jupyter kernel after changing versions. Related NumPy version errors: NumPy 2 breaking changes, SciPy NumPy 2 compatibility, Matplotlib NumPy 2 compatibility.

Frequently asked questions

Why does Numba say it needs NumPy 2.2 or less?

Numba 0.61.2 refuses to import with NumPy 2.3 or newer; its metadata requires numpy<2.3. Newer Numba releases raise the cap.

How do I fix it?

pip install "numpy<2.3" (the version in the message), or pip install -U numba numpy (numba 0.68.0 + numpy 2.4.6 on Python 3.11 in this test).

Written with AI assistance. Measured on 2026-10-24 on Linux with Python 3.11.17: numba 0.61.2 with numpy 2.3.5 and 2.2.6, numba 0.60.0 with numpy 2.2.6, then upgraded to numba 0.68.0 with numpy 2.4.6. The script ran verbatim and output was pasted unedited (paths shortened). Version caps read from PyPI metadata the same day. PlainTables is our extension; Numba and NumPy are free.