numpy.core.multiarray failed to import: fix the cv2 version mismatch

import cv2 raises ImportError: numpy.core.multiarray failed to import on the first line that touches OpenCV, and the camera never starts. Because the message names numpy, the instinct is to reinstall numpy — often several times — while the error survives every attempt. The fault is a version pair: the cv2 wheel on disk was compiled against a different NumPy C-ABI than the numpy your interpreter actually loads. This guide shows you how to read the traceback to find which environment is running, how to test the likely causes in order, and the pip commands that align numpy and the OpenCV wheel in one environment. It is written for anyone pulling frames from GigE area scan cameras or USB cameras into NumPy arrays.

What the error actually means

cv2 is a compiled extension, not a plain-Python package. numpy.core.multiarray is the C module that hands NumPy arrays to such extensions, and when OpenCV was built the compiler recorded the NumPy C-ABI level it was built against. At import time the installed numpy reports the ABI it provides; if that ABI falls outside the range the wheel was compiled for, cv2 refuses to load and Python prints exactly this ImportError.

One rule decides which side has to move: an extension compiled with NumPy 2.0 headers runs against both 1.x and 2.x, and anything compiled earlier runs only against the 1.x ABI. NumPy 2.0 arrived in mid-2024 — the OpenCV packaging tracker was still being asked when support would land in June 2024 — so a wheel built before that date pairs with a 1.x numpy only. In the other direction, a numpy older than the wheel's build-time numpy sits below the recorded floor and fails the same way. Both directions print this one error.

numpy itself almost always imports cleanly. The failing check is the pairing, not numpy in isolation, which is why reinstalling numpy again and again changes nothing.

Test the likely causes in order

Three causes cover nearly every occurrence of this error. Work down the table and stop at the first test that matches.

The first cause dominates: if numpy loads on its own, your numpy is healthy, and no amount of reinstalling numpy will repair a pairing.

The fix: align the pair in one environment

1. Exit any Python prompt. >>> means you are inside the interpreter, where pip is not a command and prints SyntaxError. Type exit() or press Ctrl-D, then run the remaining steps from the shell.

2. Run pip through the interpreter that runs the failing script, so the upgrade lands in the site-packages directory your traceback named: python3 -m pip install --upgrade numpy.
3. If the cv2 wheel is old — a pin such as opencv-python==4.1.0.25 qualifies — upgrade both packages in one command and let pip resolve a compatible set: python3 -m pip install --upgrade numpy opencv-python.
4. Prove the result: python3 -c 'import cv2' now exits silently, then rerun your script. An error about capture calls after this point is a separate, later problem, and the worked example below walks it.

Worked example: opencv-python 4.1.0.25 on Python 3.6 will not import cv2

Inputs, each with its source:

• opencv-python 4.1.0.25, pinned in the capture environment (the failing machine).
• Python 3.6 on Ubuntu 17.04 (the failing machine); the pattern is current on any distribution where the pair drifts.
• Traceback facts: the failure is raised at line 3 of cv2/__init__.py, called from line 43 of the capture script pseudo.py, and the failing cv2 loads from ~/.local/lib/python3.6/site-packages — the user site, not the system packages.
• The ABI rule: wheels built before NumPy 2.0 (mid-2024) run only on the 1.x ABI (OpenCV packaging tracker).

The rule in words: compare the installed numpy with the range the wheel recorded at build time. Ceiling check: installed major 2 against a wheel ceiling of 1 gives 2 > 1, out of range, import refused. Floor check: installed 1.x but older than the wheel's build-time numpy gives below-floor, same refusal. One error, two directions.

Trace:

1. python3 pseudo.py fails with ImportError at cv2/__init__.py line 3. The path in the traceback identifies the environment to fix: the user site under Python 3.6.
2. python3 -c 'import numpy; print(numpy.__version__)' passes and prints a version. Read the major only and apply the comparison above: 2.x is out of range for this wheel; a 1.x is in range unless it predates the wheel's build, in which case an upgrade within the 1.x line closes the gap.
3. The first fix attempt, pip install --upgrade numpy, is typed at the still-open >>> prompt and dies with SyntaxError — the upgrade never ran (the trap flagged in the fix section). Exit to the shell.
4. From the shell: python3 -m pip install --upgrade numpy, which upgrades numpy in the same user site the traceback named.
5. Check the major again and apply the same comparison. A 1.x result pairs with this wheel: rerun the script. A 2.x result cannot pair with a pre-NumPy-2.0 wheel, so upgrade the wheel too in the same environment: python3 -m pip install --upgrade opencv-python.

Result: rerunning python3 pseudo.py gets past the import. One more failure is expected on this particular script and is unrelated to numpy: cv.CaptureFromCAM, cv.QueryFrame and cv.SaveImage belong to the pre-2.x C API and raise AttributeError on any cv2 build. The current interface is cv2.VideoCapture: cap = cv2.VideoCapture(0) opens device 0, ok, frame = cap.read() pulls a frame, cap.release() closes it.

Decision for the whole case: numpy imports alone while cv2 does not — fix the pair. A pip line dies with SyntaxError — you are in the wrong prompt. The upgrade completes and the error is unchanged — pip fixed a different environment than your traceback names, which is the next section.

When upgrading numpy does not clear the error

An upgrade that completes and leaves the error unchanged is a real and common outcome — it points at the environment rather than the pair. Three things produce it:

• Wrong interpreter. pip belonged to the system Python while the script runs in a virtual environment, or the reverse. Test: python3 -m pip -V, then compare the printed path with the site-packages path in the traceback. Fix: activate that environment first, or make python3 -m pip the habit.
• Two package managers in one environment. In a conda environment, numpy installed by conda is invisible to a pip upgrade, and the copies shadow each other. Upgrade numpy with whichever manager put it there.
• A setup that reinstalls the mismatch. A requirements file pinning the old wheel, or a container rebuilt from the same image, restores the broken pair on every run. Pin one tested numpy-plus-OpenCV combination, the same discipline as pinning a single library version across a Docker build.

The habit behind all three — match the package to the interpreter before installing — is the same one that prevents the GenICam package-not-found error.

Keep the pair aligned afterwards

• Install numpy and the OpenCV wheel in one pip command; the resolver then picks a compatible set instead of you matching major versions by hand.
• Pin the working pair with exact versions in your requirements file and rebuild environments from that file.
• Before adding SDKs, GPU stacks or new wheels to a working environment, run through the GPU vision environment compatibility checks. Mixed environments produce this error and harder relatives, such as the DLL load failure caused by SDK bitness on Windows.
• Once cv2 imports cleanly, frames arrive as NumPy arrays and the failure moves up a layer: stride and dtype problems when a depth image becomes a point cloud, or a camera that fails to initialize even though the import now passes.
• OpenCV-level conflicts — two library copies in one environment — have their own trace in vision calibration tools; the OpenCV version conflict guide follows it. More fixes at this layer sit in the systems guides.

Quick checklist

• Shell, not prompt: the terminal shows $, not >>>, before any pip command — pip at the Python prompt raises SyntaxError and changes nothing.
• Right environment: the site-packages path in the traceback is the environment to fix; confirm it with python3 -m pip -V.
• Pair, not package: import numpy passing while import cv2 fails means a mismatched pair, which reinstalling numpy alone cannot fix.
• Major-version rule: a wheel built before NumPy 2.0 (mid-2024) pairs with numpy 1.x only — upgrade the wheel or pin numpy to 1.x.
• One command: upgrade numpy and opencv-python together so pip resolves a compatible set.
• Re-test after upgrading: an unchanged error means the upgrade landed in a different environment than your script runs in.

If the script you are repairing is the front end of a capture stack, choose the camera and interface for the job in the area scan camera finder, then match the rest of the chain in the build a system configurator. A stack that still will not resolve goes through the contact page.