ImportError: numpy.core.multiarray failed to import (cv2, tested)

Q: Why does import cv2 say numpy.core.multiarray failed to import?

The installed OpenCV wheel (4.8.1.78 in this test) was compiled against NumPy 1.x and NumPy 2 is installed.

Q: How do I fix numpy.core.multiarray failed to import?

pip install "numpy<2", or pip install -U opencv-python (or the -headless/-contrib package you use) together with numpy.

Q: Why did pip not prevent it?

opencv-python-headless 4.8.1.78 declares numpy>=1.21.2 with no upper bound, so pip check reports all packages compatible.

import cv2 fails with ImportError: numpy.core.multiarray failed to import, after AttributeError: _ARRAY_API not found and a NumPy 1.x/2 banner. Your OpenCV wheel was built for NumPy 1.x and NumPy 2 is installed. Pin numpy<2 or upgrade OpenCV; both tested below.

1. Reproduce: OpenCV 4.8 with NumPy 2

A Python 3.11 venv with opencv-python-headless==4.8.1.78 and numpy==2.2.6. b1.py:

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

Output (paths shortened to /venv and /usr):

numpy 2.2.6

A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.2.6 as it may crash. To support both 1.x and 2.x
versions of NumPy, modules must be compiled with NumPy 2.0.
Some module may need to rebuild instead e.g. with 'pybind11>=2.12'.

If you are a user of the module, the easiest solution will be to
downgrade to 'numpy<2' or try to upgrade the affected module.
We expect that some modules will need time to support NumPy 2.

Traceback (most recent call last):  File "b1.py", line 3, in <module>
    import cv2
  File "/venv/lib/python3.11/site-packages/cv2/__init__.py", line 181, in <module>
    bootstrap()
  File "/venv/lib/python3.11/site-packages/cv2/__init__.py", line 153, in bootstrap
    native_module = importlib.import_module("cv2")
  File "/usr/lib/python3.11/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
AttributeError: _ARRAY_API not found
Traceback (most recent call last):
  File "b1.py", line 3, in <module>
    import cv2
  File "/venv/lib/python3.11/site-packages/cv2/__init__.py", line 181, in <module>
    bootstrap()
  File "/venv/lib/python3.11/site-packages/cv2/__init__.py", line 153, in bootstrap
    native_module = importlib.import_module("cv2")
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ImportError: numpy.core.multiarray failed to import
exit status: 1

And pip sees nothing wrong:

$ pip check
All installed packages are compatible

2. What it means

The cv2 binary in opencv 4.8.1.78 was compiled against NumPy 1.x. Under NumPy 2 the import prints the A module that was compiled using NumPy 1.x cannot be run in NumPy 2.2.6 banner, then AttributeError: _ARRAY_API not found, and fails with ImportError: numpy.core.multiarray failed to import (exit status 1).
pip check passes because this opencv's metadata only asks for numpy (>=1.21.2) on Python 3.10+, with no upper bound, so pip happily installs NumPy 2 next to it.

3. Fix: pin numpy<2, or upgrade OpenCV

Option A, keep the old OpenCV:

$ pip install "numpy<2"
$ python b1.py
numpy 1.26.4
cv2 4.8.1

Option B, upgrade OpenCV (and NumPy) together; the current wheel imports fine on NumPy 2:

$ pip install -U opencv-python-headless numpy
$ python b1.py
numpy 2.4.6
cv2 5.0.0

Use the same package name you installed (opencv-python, opencv-python-headless or opencv-contrib-python); mixing them breaks cv2 in other ways. The same banner with torch or pandas: A module compiled using NumPy 1.x; with TensorFlow: TensorFlow _ARRAY_API not found. Other NumPy 2 changes: NumPy 2 breaking changes. If cv2 is not installed at all in ComfyUI: ComfyUI: No module named 'cv2'.

Frequently asked questions

Why does import cv2 say numpy.core.multiarray failed to import?

The installed OpenCV wheel (4.8.1.78 in this test) was compiled against NumPy 1.x and NumPy 2 is installed.

How do I fix numpy.core.multiarray failed to import?

pip install "numpy<2", or pip install -U opencv-python (or the -headless/-contrib package you use) together with numpy.

Why did pip not prevent it?

opencv-python-headless 4.8.1.78 declares numpy>=1.21.2 with no upper bound, so pip check reports all packages compatible.

Written with AI assistance. Measured on 2026-10-24 on Linux with Python 3.11.17: opencv-python-headless 4.8.1.78 with numpy 2.2.6 and 1.26.4, then upgraded to opencv-python-headless 5.0.0 with numpy 2.4.6. The script ran verbatim and the output was pasted unedited (paths shortened). PlainTables is our extension; OpenCV and NumPy are free.