Fix: numpy.core.multiarray failed to import (NumPy 2)

ImportError: numpy.core.multiarray failed to import means a package with compiled code was built for NumPy 1.x, but you have NumPy 2 installed. Fix it by upgrading that package, or by going back to NumPy 1.x:

pip install --upgrade matplotlib      # or whichever package fails
# or
pip install "numpy<2"

I reproduced this error for real in a fresh virtual environment, using matplotlib 3.7.5 with NumPy 2.1.3 on Python 3.11, then fixed it. My main setup runs Python 3.12.5.

Below I’ll show what the full error looks like, why it happens, how to find the package at fault, and both fixes with the commands I ran.

What the numpy.core.multiarray error looks like

The script only imports matplotlib and draws a bar chart. On NumPy 2, the import itself fails before any of your code runs:

import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt

plt.bar(["Austin", "Denver", "Boston"], [1250.50, 980.25, 1430.00])
plt.savefig("sales.png")
print("chart saved")

Output:

A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.1.3 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 "C:\pyguides\plot_sales.py", line 1, in <module>
    import matplotlib
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\__init__.py", line 142, in <module>
    from . import _api, _version, cbook, _docstring, rcsetup
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\rcsetup.py", line 27, in <module>
    from matplotlib.colors import Colormap, is_color_like
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\colors.py", line 56, in <module>
    from matplotlib import _api, _cm, cbook, scale
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\scale.py", line 22, in <module>
    from matplotlib.ticker import (
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\ticker.py", line 138, in <module>
    from matplotlib import transforms as mtransforms
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\transforms.py", line 49, in <module>
    from matplotlib._path import (
AttributeError: _ARRAY_API not found
Traceback (most recent call last):
  File "C:\pyguides\plot_sales.py", line 1, in <module>
    import matplotlib
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\__init__.py", line 142, in <module>
    from . import _api, _version, cbook, _docstring, rcsetup
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\rcsetup.py", line 27, in <module>
    from matplotlib.colors import Colormap, is_color_like
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\colors.py", line 56, in <module>
    from matplotlib import _api, _cm, cbook, scale
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\scale.py", line 22, in <module>
    from matplotlib.ticker import (
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\ticker.py", line 138, in <module>
    from matplotlib import transforms as mtransforms
  File "C:\pyguides\npenv\Lib\site-packages\matplotlib\transforms.py", line 49, in <module>
    from matplotlib._path import (
ImportError: numpy.core.multiarray failed to import

Read the top message carefully. NumPy itself tells you the two options: downgrade to numpy<2 or upgrade the affected module. The traceback shows which module that is, here matplotlib._path.

Why does numpy.core.multiarray fail to import?

Packages like matplotlib, pandas, SciPy and OpenCV ship compiled C extensions. Those extensions are built against a specific NumPy binary interface, and NumPy 2.0 changed that interface.

So an old wheel built for NumPy 1.x can’t load into NumPy 2. It usually happens when something upgrades NumPy without upgrading the packages that depend on it, or when an old version is pinned in a requirements file.

Finding the package that isn’t NumPy 2 compatible

Check your versions, then ask your package manager about conflicts. uv pip check or pip check points straight at the problem:

npenv\Scripts\python -c "import numpy, importlib.metadata as m; print('numpy', numpy.__version__, '| matplotlib', m.version('matplotlib'))"
uv pip check --python npenv

Output:

numpy 2.1.3 | matplotlib 3.7.5
Using Python 3.11.17 environment at: npenv
Checked 11 packages in 1ms
Found 1 incompatibility
The package `matplotlib` requires `numpy>=1.20,<2`, but `2.1.3` is installed

Fix 1: Upgrade the module compiled for NumPy 1.x

Most popular packages released NumPy 2 compatible versions in 2024. Upgrading matplotlib to 3.9 or later fixed it immediately:

uv pip install --python npenv "matplotlib>=3.9"
npenv\Scripts\python -c "import numpy, importlib.metadata as m; print('numpy', numpy.__version__, '| matplotlib', m.version('matplotlib'))"
npenv\Scripts\python plot_sales.py

Output:

Using Python 3.11.17 environment at: npenv
Resolved 11 packages in 18ms
Uninstalled 1 package in 97ms
Installed 1 package in 204ms
 - matplotlib==3.7.5
 + matplotlib==3.11.2
numpy 2.1.3 | matplotlib 3.11.2
chart saved

With plain pip the command is python -m pip install --upgrade matplotlib. Using python -m pip makes sure you upgrade the same Python that runs your script; ModuleNotFoundError after pip install explains why that matters.

Fix 2: Downgrade NumPy to 1.x

If you can’t upgrade the package, for example an old internal library or a package that’s no longer maintained, pin NumPy below 2:

python -m pip install "numpy<2"

Then record it in your project’s requirements so it doesn’t drift again. See pip install -r requirements.txt and pip install a specific version.

Common packages and the first NumPy 2 compatible versions

Package	NumPy 2 support from
pandas	2.2.2
matplotlib	3.8.4
SciPy	1.13.0
scikit-learn	1.4.2
opencv-python	4.10.0.84

Upgrading to any recent release is the simple rule. If you’re stuck with an older Python that newer wheels don’t support, that’s usually the moment to pin numpy<2.

Preventing the error in new projects

• Use one virtual environment per project; see Python virtual environments.
• Install your main packages together, so the resolver picks compatible versions.
• Run pip check after big upgrades.
• Pin versions for deployments with a lock file or pip freeze.

Related fixes for import and install problems:

• Python import from another directory
• Types of errors in Python
• Install multiple Python versions
• Print a stack trace in Python

Frequently asked questions