Nov 9, 2025
diff --git a/doc/api/next_api_changes/deprecations/30737-TH.rst b/doc/api/next_api_changes/deprecations/30737-TH.rst
 The *canvas* parameter to ``MultiCursor``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 ... is deprecated. It has been unused for a while already.

 Please remove the parameter and change the call from
 ``MultiCursor(canvas, axes)`` to ``MultiCursor(axes)``. Both calls are
 valid throughout the deprecation period.
diff --git a/galleries/examples/widgets/multicursor.py b/galleries/examples/widgets/multicursor.py
 fig,ax3=plt.subplots()
 ax3.plot(t,s3)

 multi=MultiCursor(None,(ax1,ax2,ax3),color='r',lw=1)
 multi=MultiCursor((ax1,ax2,ax3),color='r',lw=1)
 plt.show()

 # %%
diff --git a/lib/matplotlib/tests/test_widgets.py b/lib/matplotlib/tests/test_widgets.py
 import operator
 from unittest import mock

 import matplotlib as mpl
 from matplotlib.backend_bases import DrawEvent, KeyEvent, MouseEvent
 import matplotlib.colors as mcolors
 import matplotlib.widgets as widgets

 @pytest.mark.parametrize("horizOn", [False, True])
 @pytest.mark.parametrize("vertOn", [False, True])
 def test_MultiCursor(horizOn, vertOn):
 @pytest.mark.parametrize("with_deprecated_canvas", [False, True])
 def test_MultiCursor(horizOn, vertOn, with_deprecated_canvas):
    fig = plt.figure()
    (ax1, ax3) = fig.subplots(2, sharex=True)
    ax2 = plt.figure().subplots()

    # useblit=false to avoid having to draw the figure to cache the renderer
    multi = widgets.MultiCursor(
        None, (ax1, ax2), useblit=False, horizOn=horizOn, vertOn=vertOn
    )
    if with_deprecated_canvas:
        with pytest.warns(mpl.MatplotlibDeprecationWarning, match=r"canvas.*deprecat"):
            multi = widgets.MultiCursor(
                None, (ax1, ax2), useblit=False, horizOn=horizOn, vertOn=vertOn
            )
    else:
        # useblit=false to avoid having to draw the figure to cache the renderer
        multi = widgets.MultiCursor(
            (ax1, ax2), useblit=False, horizOn=horizOn, vertOn=vertOn
        )

    # Only two of the axes should have a line drawn on them.
    assert len(multi.vlines) == 2
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
    Provide a vertical (default) and/or horizontal line cursor shared between
    multiple Axes.

    Call signatures::

        MultiCursor(axes, *, ...)
        MultiCursor(canvas, axes, *, ...)  # deprecated

    For the cursor to remain responsive you must keep a reference to it.

    Parameters
    ----------
    canvas : object
        This parameter is entirely unused and only kept for back-compatibility.
        This parameter is entirely unused.

        .. deprecated:: 3.11

    axes : list of `~matplotlib.axes.Axes`
        The `~.axes.Axes` to attach the cursor to.
    See :doc:`/gallery/widgets/multicursor`.
    """

    def __init__(self,canvas, axes, *, useblit=True, horizOn=False, vertOn=True,
    def __init__(self,*args, useblit=True, horizOn=False, vertOn=True,
                 **lineprops):
        # canvas is stored only to provide the deprecated .canvas attribute;
        # once it goes away the unused argument won't need to be stored at all.
        self._canvas = canvas
        # Deprecation of canvas as the first attribute. When the deprecation exprires:
        # - change the signature to __init__(self, axes, *, ...)
        # - delete the "Call signatures" block in the docstring
        # - delete this block
        kwargs = {k: lineprops.pop(k)
                  for k in list(lineprops) if k in ("canvas", "axes")}
        params = _api.select_matching_signature(
            [lambda axes: locals(), lambda canvas, axes: locals()], *args, **kwargs)
        if "canvas" in params:
            _api.warn_deprecated(
                "3.11",
                message="The canvas parameter in MultiCursor is unused and deprecated "
                "since  %(since)s. Please remove it and call MultiCursor(axes) "
                "instead of MultiCursor(canvas, axes). The latter will start raising "
                "an error in %(removal)s"
            )
        axes = params["axes"]

        self.axes = axes
        self.horizOn = horizOn
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,8 @@
		The canvas parameter to ``MultiCursor``
		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		... is deprecated. It has been unused for a while already.

		Please remove the parameter and change the call from
		``MultiCursor(canvas, axes)`` to ``MultiCursor(axes)``. Both calls are
		valid throughout the deprecation period.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -26,7 +26,7 @@
		fig,ax3=plt.subplots()
		ax3.plot(t,s3)

		multi=MultiCursor(None,(ax1,ax2,ax3),color='r',lw=1)
		multi=MultiCursor((ax1,ax2,ax3),color='r',lw=1)
		plt.show()

		# %%
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,6 +3,7 @@
		import operator
		from unittest import mock

		import matplotlib as mpl
		from matplotlib.backend_bases import DrawEvent, KeyEvent, MouseEvent
		import matplotlib.colors as mcolors
		import matplotlib.widgets as widgets
Expand DownExpand Up		@@ -1680,15 +1681,22 @@ def test_polygon_selector_clear_method(ax):

		@pytest.mark.parametrize("horizOn", [False, True])
		@pytest.mark.parametrize("vertOn", [False, True])
		def test_MultiCursor(horizOn, vertOn):
		@pytest.mark.parametrize("with_deprecated_canvas", [False, True])
		def test_MultiCursor(horizOn, vertOn, with_deprecated_canvas):
		fig = plt.figure()
		(ax1, ax3) = fig.subplots(2, sharex=True)
		ax2 = plt.figure().subplots()

		# useblit=false to avoid having to draw the figure to cache the renderer
		multi = widgets.MultiCursor(
		None, (ax1, ax2), useblit=False, horizOn=horizOn, vertOn=vertOn
		)
		if with_deprecated_canvas:
		with pytest.warns(mpl.MatplotlibDeprecationWarning, match=r"canvas.*deprecat"):
		multi = widgets.MultiCursor(
		None, (ax1, ax2), useblit=False, horizOn=horizOn, vertOn=vertOn
		)
		else:
		# useblit=false to avoid having to draw the figure to cache the renderer
		multi = widgets.MultiCursor(
		(ax1, ax2), useblit=False, horizOn=horizOn, vertOn=vertOn
		)

		# Only two of the axes should have a line drawn on them.
		assert len(multi.vlines) == 2
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1989,12 +1989,19 @@ class MultiCursor(Widget):
		Provide a vertical (default) and/or horizontal line cursor shared between
		multiple Axes.

		Call signatures::

		MultiCursor(axes, *, ...)
		MultiCursor(canvas, axes, *, ...) # deprecated

		For the cursor to remain responsive you must keep a reference to it.

		Parameters
		----------
		canvas : object
		This parameter is entirely unused and only kept for back-compatibility.
		This parameter is entirely unused.

		.. deprecated:: 3.11

		axes : list of `~matplotlib.axes.Axes`
		The `~.axes.Axes` to attach the cursor to.
Expand All		@@ -2021,11 +2028,25 @@ class MultiCursor(Widget):
		See :doc:`/gallery/widgets/multicursor`.
		"""

		def __init__(self,canvas, axes, *, useblit=True, horizOn=False, vertOn=True,
		def __init__(self,*args, useblit=True, horizOn=False, vertOn=True,
		**lineprops):
		# canvas is stored only to provide the deprecated .canvas attribute;
		# once it goes away the unused argument won't need to be stored at all.
		self._canvas = canvas
		# Deprecation of canvas as the first attribute. When the deprecation exprires:
		# - change the signature to __init__(self, axes, *, ...)
		# - delete the "Call signatures" block in the docstring
		# - delete this block
		kwargs = {k: lineprops.pop(k)
		for k in list(lineprops) if k in ("canvas", "axes")}
		params = _api.select_matching_signature(
		[lambda axes: locals(), lambda canvas, axes: locals()], args, *kwargs)
		if "canvas" in params:
		_api.warn_deprecated(
		"3.11",
		message="The canvas parameter in MultiCursor is unused and deprecated "
		"since %(since)s. Please remove it and call MultiCursor(axes) "
		"instead of MultiCursor(canvas, axes). The latter will start raising "
		"an error in %(removal)s"
		)
		axes = params["axes"]

		self.axes = axes
		self.horizOn = horizOn
Expand Down