Matplotlib and NumPy 2 compatibility (tested)

Matplotlib 3.8.3 and older fail at import matplotlib under NumPy 2 with ImportError: numpy.core.multiarray failed to import. Matplotlib 3.8.4 is the first release that supports NumPy 2. Pin numpy<2 or upgrade; tested below.

1. Reproduce: Matplotlib 3.8.3 with NumPy 2

A Python 3.11 venv with matplotlib==3.8.3, then numpy==2.2.6 installed in a second command (a single command that asks for both is refused, because 3.8.3 requires numpy<2). b1.py:

import numpy
print("numpy", numpy.__version__)
import matplotlib
print("matplotlib", matplotlib.__version__)
matplotlib.use("Agg")
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])
plt.savefig("out.png")
print("saved out.png")

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

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 matplotlib
  File "/venv/lib/python3.11/site-packages/matplotlib/__init__.py", line 161, in <module>
    from . import _api, _version, cbook, _docstring, rcsetup
  File "/venv/lib/python3.11/site-packages/matplotlib/rcsetup.py", line 27, in <module>
    from matplotlib.colors import Colormap, is_color_like
  File "/venv/lib/python3.11/site-packages/matplotlib/colors.py", line 57, in <module>
    from matplotlib import _api, _cm, cbook, scale
  File "/venv/lib/python3.11/site-packages/matplotlib/scale.py", line 22, in <module>
    from matplotlib.ticker import (
  File "/venv/lib/python3.11/site-packages/matplotlib/ticker.py", line 143, in <module>
    from matplotlib import transforms as mtransforms
  File "/venv/lib/python3.11/site-packages/matplotlib/transforms.py", line 49, in <module>
    from matplotlib._path import (
Traceback (most recent call last):
  File "/venv/lib/python3.11/site-packages/numpy/core/_multiarray_umath.py", line 44, in __getattr__
    raise ImportError(msg)
ImportError: 
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 matplotlib
  File "/venv/lib/python3.11/site-packages/matplotlib/__init__.py", line 161, in <module>
    from . import _api, _version, cbook, _docstring, rcsetup
  File "/venv/lib/python3.11/site-packages/matplotlib/rcsetup.py", line 27, in <module>
    from matplotlib.colors import Colormap, is_color_like
  File "/venv/lib/python3.11/site-packages/matplotlib/colors.py", line 57, in <module>
    from matplotlib import _api, _cm, cbook, scale
  File "/venv/lib/python3.11/site-packages/matplotlib/scale.py", line 22, in <module>
    from matplotlib.ticker import (
  File "/venv/lib/python3.11/site-packages/matplotlib/ticker.py", line 143, in <module>
    from matplotlib import transforms as mtransforms
  File "/venv/lib/python3.11/site-packages/matplotlib/transforms.py", line 49, in <module>
    from matplotlib._path import (
ImportError: numpy.core.multiarray failed to import

Unlike SciPy or OpenCV there is no _ARRAY_API not found line here: the inner error is an ImportError raised from numpy/core/_multiarray_umath.py whose message is the NumPy 1.x banner itself, and the outer one is ImportError: numpy.core.multiarray failed to import from matplotlib._path. It fails at import matplotlib, before any plotting. The resolver states the conflict:

$ uv pip check
Found 1 incompatibility
The package `matplotlib` requires `numpy>=1.21,<2`, but `2.2.6` is installed

2. Which Matplotlib versions support NumPy 2

From the PyPI Requires-Dist metadata, confirmed by running b1.py on 3.7.5, 3.8.3 (both fail as above) and 3.8.4 (works). Matplotlib 3.8.4 is the first release that supports NumPy 2.

3. Fix: pin numpy<2, or upgrade Matplotlib to 3.8.4+

$ pip install "numpy<2"
$ python b1.py
numpy 1.26.4
matplotlib 3.8.3
saved out.png

Smallest upgrade that keeps NumPy 2:

$ pip install "matplotlib==3.8.4"
$ python b1.py
numpy 2.2.6
matplotlib 3.8.4
saved out.png

Or the latest (on Python 3.11 this resolved to Matplotlib 3.11.2 with NumPy 2.4.6):

$ pip install -U matplotlib numpy
$ python b1.py
numpy 2.4.6
matplotlib 3.11.2
saved out.png

4. The opposite error: Matplotlib requires numpy>=1.25

Going the other way (new Matplotlib, old NumPy) gives a clear message instead of a C-API crash. Matplotlib 3.11.2 with numpy 1.24.4 forced in afterwards, same b1.py:

numpy 1.24.4
Traceback (most recent call last):
  File "b1.py", line 3, in <module>
    import matplotlib
  File "/venv/lib/python3.11/site-packages/matplotlib/__init__.py", line 265, in <module>
    _check_versions()
  File "/venv/lib/python3.11/site-packages/matplotlib/__init__.py", line 261, in _check_versions
    raise ImportError(f"Matplotlib requires {modname}>={minver}; "
ImportError: Matplotlib requires numpy>=1.25; you have 1.24.4

Fix with pip install -U numpy, or pin an older Matplotlib if something else holds NumPy back.

In a notebook, restart the kernel after changing versions: a running process keeps the NumPy it already imported. New deprecations after upgrading: Matplotlib deprecation warnings. Same NumPy 2 problem in other libraries: SciPy, scikit-learn, OpenCV, pandas, the general banner. All changes: NumPy 2 breaking changes.

Written with AI assistance. Measured on 2026-10-24 on Linux with Python 3.11.17: matplotlib 3.7.5, 3.8.3 and 3.8.4 with numpy 2.2.6, 3.8.3 with numpy 1.26.4, an upgrade to matplotlib 3.11.2 with numpy 2.4.6, and matplotlib 3.11.2 with numpy 1.24.4. The script ran verbatim and output was pasted unedited (paths shortened). Version pins read from PyPI metadata the same day. PlainTables is our extension; Matplotlib and NumPy are free.