MatplotlibDeprecationWarning: fix, silence, find it (tested)

A MatplotlibDeprecationWarning means a call still works but will be removed in a named future version (e.g. boxplot(vert=False) → use orientation="horizontal"; positional hist range → pass range=). Apply the replacement the message names, or filter it with warnings.filterwarnings("ignore", category=MatplotlibDeprecationWarning).

1. What the warnings say (and the replacement each one names)

Run with python b1.py (matplotlib 3.11.2, numpy 2.5.4, Python 3.13.5):

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

print("matplotlib", matplotlib.__version__)
print(matplotlib.MatplotlibDeprecationWarning.__mro__[1])
data = np.random.default_rng(0).normal(size=100)
fig, ax = plt.subplots()
ax.boxplot(data, vert=False)
ax.hist(data, 10, (-3, 3))
ax.pie([1, 2], [0, 0.1])
print("done")

Output:

matplotlib 3.11.2
<class 'DeprecationWarning'>
/tmp/md403/b1.py:10: MatplotlibDeprecationWarning: vert: bool was deprecated in Matplotlib 3.11 and will be removed in 3.13. Use orientation: {'vertical', 'horizontal'} instead.
  ax.boxplot(data, vert=False)
/tmp/md403/b1.py:11: MatplotlibDeprecationWarning: Passing the range parameter of hist() positionally is deprecated since Matplotlib 3.10; the parameter will become keyword-only in 3.12.
  ax.hist(data, 10, (-3, 3))
/tmp/md403/b1.py:12: MatplotlibDeprecationWarning: Passing the explode parameter of pie() positionally is deprecated since Matplotlib 3.10; the parameter will become keyword-only in 3.12.
  ax.pie([1, 2], [0, 0.1])
done

A MatplotlibDeprecationWarning is not an error: the plot is drawn and the script continues (done). It tells you the call will stop working in a named future version, and the message usually names the fix:

• boxplot(..., vert=False) → orientation="horizontal" (the same vert deprecation applies to violinplot). vert is removed in 3.13.
• "Passing the X parameter of Y() positionally" → pass it by name: ax.hist(data, 10, range=(-3, 3)), ax.pie([1, 2], explode=[0, 0.1]). In 3.12 the positional form becomes a TypeError.

The second printed line shows that MatplotlibDeprecationWarning is a subclass of Python's DeprecationWarning, which matters for section 3.

2. Silence it, or turn it into an error

import warnings
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
from matplotlib import MatplotlibDeprecationWarning

warnings.filterwarnings("ignore", category=MatplotlibDeprecationWarning)
fig, ax = plt.subplots()
ax.boxplot([1, 2, 3], vert=False)
print("silenced: no warning above")

warnings.filterwarnings("error", category=MatplotlibDeprecationWarning)
try:
    ax.boxplot([1, 2, 3], vert=False)
except MatplotlibDeprecationWarning as e:
    print("raised:", type(e).__name__)

warnings.resetwarnings()
ax.boxplot([1, 2, 3], orientation="horizontal")
print("orientation='horizontal': no warning")

Output:

silenced: no warning above
raised: MatplotlibDeprecationWarning
orientation='horizontal': no warning

• warnings.filterwarnings("ignore", category=MatplotlibDeprecationWarning) hides only matplotlib's deprecation warnings, not other warnings. Import the class from matplotlib directly.
• The "error" action raises the warning as an exception, which is the quickest way to find where a deprecated call comes from (the traceback points at it).
• Better than silencing: switch to the replacement (orientation="horizontal" above), which gives no warning.

3. Why you sometimes never see the warning (and the seaborn style that already broke)

helper.py contains ax.boxplot([1, 2, 3], vert=False) inside a function draw(ax), and b3.py imports it:

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

fig, ax = plt.subplots()
helper.draw(ax)   # the deprecated call is inside an imported module
print("helper.draw done")
for name in ["seaborn", "seaborn-v0_8"]:
    try:
        plt.style.use(name)
        print(f"style {name!r}: OK")
    except OSError as e:
        print(f"style {name!r}: OSError: {str(e)[:90]}")

Output:

$ python b3.py
helper.draw done
style 'seaborn': OSError: 'seaborn' is not a valid package style, path of style file, URL of style file, or library 
style 'seaborn-v0_8': OK

$ python -W default::DeprecationWarning b3.py
/tmp/md403/helper.py:2: MatplotlibDeprecationWarning: vert: bool was deprecated in Matplotlib 3.11 and will be removed in 3.13. Use orientation: {'vertical', 'horizontal'} instead.
  ax.boxplot([1, 2, 3], vert=False)
helper.draw done

$ python -W error::DeprecationWarning b3.py   # last 4 lines
  File "/tmp/fx384/ve/lib/python3.13/site-packages/matplotlib/_api/__init__.py", line 494, in warn_external
    warnings.warn(message, category, **kwargs)
    ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
matplotlib._api.deprecation.MatplotlibDeprecationWarning: vert: bool was deprecated in Matplotlib 3.11 and will be removed in 3.13. Use orientation: {'vertical', 'horizontal'} instead.

• With no flags, the same deprecated call printed nothing because it ran in an imported module. Python's default filters show DeprecationWarning only when the offending line is in __main__, the script you ran. Code in your own modules or packages upgrades silently until the removal release breaks it.
• -W default::DeprecationWarning (or PYTHONWARNINGS=default::DeprecationWarning) makes it visible and points at helper.py:2. -W error::DeprecationWarning turns it into an exception; pytest shows deprecation warnings in its warnings summary by default (see pytest filterwarnings error).
• A deprecation that has completed is no longer a warning: plt.style.use("seaborn") now raises OSError. The old seaborn styles were renamed to seaborn-v0_8 (and seaborn-v0_8-darkgrid etc.), which still works.

Related: matplotlib not showing plot · matplotlib legend not showing · numpy 2 breaking changes.

Written with AI assistance. Measured on 2026-10-23 with matplotlib 3.11.2, numpy 2.5.4 and Python 3.13.5 on Linux (Agg backend). Each script was run verbatim and the output pasted unedited. PlainTables is our extension; matplotlib is free.