# Deprecations

## Parameters to `plt.figure()` and the `Figure` constructor

All parameters to [.pyplot.figure]{.title-ref} and the
[.Figure]{.title-ref} constructor, other than *num*, *figsize*, and
*dpi*, will become keyword-only after a deprecation period.

## Deprecation aliases in cbook

The module `matplotlib.cbook.deprecation` was previously deprecated in
Matplotlib 3.4, along with deprecation-related API in
`matplotlib.cbook`. Due to technical issues,
`matplotlib.cbook.MatplotlibDeprecationWarning` and
`matplotlib.cbook.mplDeprecation` did not raise deprecation warnings on
use. Changes in Python have now made it possible to warn when these
aliases are being used.

In order to avoid downstream breakage, these aliases will now warn, and
their removal has been pushed from 3.6 to 3.8 to give time to notice
said warnings. As replacement, please use
[matplotlib.MatplotlibDeprecationWarning]{.title-ref}.

## `Axes` subclasses should override `clear` instead of `cla`

For clarity, [.axes.Axes.clear]{.title-ref} is now preferred over
[.Axes.cla]{.title-ref}. However, for backwards compatibility, the
latter will remain as an alias for the former.

For additional compatibility with third-party libraries, Matplotlib will
continue to call the `cla` method of any [\~.axes.Axes]{.title-ref}
subclasses if they define it. In the future, this will no longer occur,
and Matplotlib will only call the `clear` method in
[\~.axes.Axes]{.title-ref} subclasses.

It is recommended to define only the `clear` method when on Matplotlib
3.6, and only `cla` for older versions.

## Pending deprecation top-level cmap registration and access functions in `mpl.cm`

As part of a [multi-step
process](https://github.com/matplotlib/matplotlib/issues/20853) we are
refactoring the global state for managing the registered colormaps.

In Matplotlib 3.5 we added a [.ColormapRegistry]{.title-ref} class and
exposed an instance at the top level as `matplotlib.colormaps`. The
existing top level functions in [matplotlib.cm]{.title-ref} (`get_cmap`,
`register_cmap`, `unregister_cmap`) were changed to be aliases around
the same instance.

In Matplotlib 3.6 we have marked those top level functions as pending
deprecation with the intention of deprecation in Matplotlib 3.7. The
following functions have been marked for pending deprecation:

-   `matplotlib.cm.get_cmap`; use `matplotlib.colormaps[name]` instead
    if you have a [str]{.title-ref}.

    **Added 3.6.1** Use
    [matplotlib.cm.ColormapRegistry.get_cmap]{.title-ref} if you have a
    string, [None]{.title-ref} or a
    [matplotlib.colors.Colormap]{.title-ref} object that you want to
    convert to a [matplotlib.colors.Colormap]{.title-ref} instance.

-   `matplotlib.cm.register_cmap`; use [matplotlib.colormaps.register
    \<.ColormapRegistry.register\>]{.title-ref} instead

-   `matplotlib.cm.unregister_cmap`; use
    [matplotlib.colormaps.unregister
    \<.ColormapRegistry.unregister\>]{.title-ref} instead

-   `matplotlib.pyplot.register_cmap`; use
    [matplotlib.colormaps.register
    \<.ColormapRegistry.register\>]{.title-ref} instead

The [matplotlib.pyplot.get_cmap]{.title-ref} function will stay
available for backward compatibility.

## Pending deprecation of layout methods

The methods [\~.Figure.set_tight_layout]{.title-ref},
[\~.Figure.set_constrained_layout]{.title-ref}, are discouraged, and now
emit a [PendingDeprecationWarning]{.title-ref} in favor of explicitly
referencing the layout engine via `figure.set_layout_engine('tight')`
and `figure.set_layout_engine('constrained')`. End users should not see
the warning, but library authors should adjust.

The methods [\~.Figure.set_constrained_layout_pads]{.title-ref} and
[\~.Figure.get_constrained_layout_pads]{.title-ref} are will be
deprecated in favor of `figure.get_layout_engine().set()` and
`figure.get_layout_engine().get()`, and currently emit a
[PendingDeprecationWarning]{.title-ref}.

## seaborn styles renamed

Matplotlib currently ships many style files inspired from the seaborn
library (\"seaborn\", \"seaborn-bright\", \"seaborn-colorblind\", etc.)
but they have gone out of sync with the library itself since the release
of seaborn 0.9. To prevent confusion, the style files have been renamed
\"seaborn-v0_8\", \"seaborn-v0_8-bright\", \"seaborn-v0_8-colorblind\",
etc. Users are encouraged to directly use seaborn to access the
up-to-date styles.

## Auto-removal of overlapping Axes by `plt.subplot` and `plt.subplot2grid`

Previously, [.pyplot.subplot]{.title-ref} and
[.pyplot.subplot2grid]{.title-ref} would automatically remove
preexisting Axes that overlap with the newly added Axes. This behavior
was deemed confusing, and is now deprecated. Explicitly call
`ax.remove()` on Axes that need to be removed.

## Passing *linefmt* positionally to `stem` is undeprecated

Positional use of all formatting parameters in
[\~.Axes.stem]{.title-ref} has been deprecated since Matplotlib 3.5.
This deprecation is relaxed so that one can still pass *linefmt*
positionally, i.e. `stem(x, y, 'r')`.

## `stem(..., use_line_collection=False)`

\... is deprecated with no replacement. This was a compatibility
fallback to a former more inefficient representation of the stem lines.

## Positional / keyword arguments

Passing all but the very few first arguments positionally in the
constructors of Artists is deprecated. Most arguments will become
keyword-only in a future version.

Passing too many positional arguments to `tripcolor` is now deprecated
(extra arguments were previously silently ignored).

Passing *emit* and *auto* parameters of `set_xlim`, `set_ylim`,
`set_zlim`, `set_rlim` positionally is deprecated; they will become
keyword-only in a future release.

The *transOffset* parameter of
[.Collection.set_offset_transform]{.title-ref} and the various
`create_collection` methods of legend handlers has been renamed to
*offset_transform* (consistently with the property name).

Calling `MarkerStyle()` with no arguments or `MarkerStyle(None)` is
deprecated; use `MarkerStyle("")` to construct an empty marker style.

`Axes.get_window_extent` / `Figure.get_window_extent` accept only
*renderer*. This aligns the API with the general
[.Artist.get_window_extent]{.title-ref} API. All other parameters were
ignored anyway.

The *cleared* parameter of `get_renderer`, which only existed for
AGG-based backends, has been deprecated. Use `renderer.clear()` instead
to explicitly clear the renderer buffer.

## Methods to set parameters in `LogLocator` and `LogFormatter*`

In [\~.LogFormatter]{.title-ref} and derived subclasses, the methods
`base` and `label_minor` for setting the respective parameter are
deprecated and replaced by `set_base` and `set_label_minor`,
respectively.

In [\~.LogLocator]{.title-ref}, the methods `base` and `subs` for
setting the respective parameter are deprecated. Instead, use
`set_params(base=..., subs=...)`.

## `Axes.get_renderer_cache`

The canvas now takes care of the renderer and whether to cache it or
not. The alternative is to call `axes.figure.canvas.get_renderer()`.

## Groupers from `get_shared_x_axes` / `get_shared_y_axes` will be immutable

Modifications to the Groupers returned by `get_shared_x_axes` and
`get_shared_y_axes` are deprecated. In the future, these methods will
return immutable views on the grouper structures. Note that previously,
calling e.g. `join()` would already fail to set up the correct
structures for sharing axes; use [.Axes.sharex]{.title-ref} or
[.Axes.sharey]{.title-ref} instead.

## Unused methods in `Axis`, `Tick`, `XAxis`, and `YAxis`

`Tick.label` has been pending deprecation since 3.1 and is now
deprecated. Use `Tick.label1` instead.

The following methods are no longer used and deprecated without a
replacement:

-   `Axis.get_ticklabel_extents`
-   `Tick.get_pad_pixels`
-   `XAxis.get_text_heights`
-   `YAxis.get_text_widths`

## `mlab.stride_windows`

\... is deprecated. Use `np.lib.stride_tricks.sliding_window_view`
instead (or `np.lib.stride_tricks.as_strided` on NumPy \< 1.20).

## Event handlers

The `draw_event`, `resize_event`, `close_event`, `key_press_event`,
`key_release_event`, `pick_event`, `scroll_event`, `button_press_event`,
`button_release_event`, `motion_notify_event`, `enter_notify_event` and
`leave_notify_event` methods of [.FigureCanvasBase]{.title-ref} are
deprecated. They had inconsistent signatures across backends, and made
it difficult to improve event metadata.

In order to trigger an event on a canvas, directly construct an
[.Event]{.title-ref} object of the correct class and call
`canvas.callbacks.process(event.name, event)`.

## Widgets

All parameters to `MultiCursor` starting from *useblit* are becoming
keyword-only (passing them positionally is deprecated).

The `canvas` and `background` attributes of `MultiCursor` are deprecated
with no replacement.

The *visible* attribute of Selector widgets has been deprecated; use
`set_visible` or `get_visible` instead.

The *state_modifier_keys* attribute of Selector widgets has been
privatized and the modifier keys must be set when creating the widget.

## `Axes3D.dist`

\... has been privatized. Use the *zoom* keyword argument in
[.Axes3D.set_box_aspect]{.title-ref} instead.

## 3D Axis

The previous constructor of [.axis3d.Axis]{.title-ref}, with signature
`(self, adir, v_intervalx, d_intervalx, axes, *args, rotate_label=None, **kwargs)`
is deprecated in favor of a new signature closer to the one of 2D Axis;
it is now `(self, axes, *, rotate_label=None, **kwargs)` where `kwargs`
are forwarded to the 2D Axis constructor. The axis direction is now
inferred from the axis class\' `axis_name` attribute (as in the 2D
case); the `adir` attribute is deprecated.

The `init3d` method of 3D Axis is also deprecated; all the relevant
initialization is done as part of the constructor.

The `d_interval` and `v_interval` attributes of 3D Axis are deprecated;
use `get_data_interval` and `get_view_interval` instead.

The `w_xaxis`, `w_yaxis`, and `w_zaxis` attributes of `Axis3D` have been
pending deprecation since 3.1. They are now deprecated. Instead use
`xaxis`, `yaxis`, and `zaxis`.

`mplot3d.axis3d.Axis.set_pane_pos` is deprecated. This is an internal
method where the provided values are overwritten during drawing. Hence,
it does not serve any purpose to be directly accessible.

The two helper functions `mplot3d.axis3d.move_from_center` and
`mplot3d.axis3d.tick_update_position` are considered internal and
deprecated. If these are required, please vendor the code from the
corresponding private methods `_move_from_center` and
`_tick_update_position`.

## `Figure.callbacks` is deprecated

The Figure `callbacks` property is deprecated. The only signal was
\"dpi_changed\", which can be replaced by connecting to the
\"resize_event\" on the canvas
`figure.canvas.mpl_connect("resize_event", func)` instead.

## `FigureCanvas` without a `required_interactive_framework` attribute

Support for such canvas classes is deprecated. Note that canvas classes
which inherit from `FigureCanvasBase` always have such an attribute.

## Backend-specific deprecations

-   `backend_gtk3.FigureManagerGTK3Agg` and
    `backend_gtk4.FigureManagerGTK4Agg`; directly use
    `backend_gtk3.FigureManagerGTK3` and
    `backend_gtk4.FigureManagerGTK4` instead.
-   The *window* parameter to `backend_gtk3.NavigationToolbar2GTK3` had
    no effect, and is now deprecated.
-   `backend_gtk3.NavigationToolbar2GTK3.win`
-   `backend_gtk3.RendererGTK3Cairo` and
    `backend_gtk4.RendererGTK4Cairo`; use [.RendererCairo]{.title-ref}
    instead, which has gained the `set_context` method, which also
    auto-infers the size of the underlying surface.
-   `backend_cairo.RendererCairo.set_ctx_from_surface` and
    `backend_cairo.RendererCairo.set_width_height` in favor of
    [.RendererCairo.set_context]{.title-ref}.
-   `backend_gtk3.error_msg_gtk`
-   `backend_gtk3.icon_filename` and `backend_gtk3.window_icon`
-   `backend_macosx.NavigationToolbar2Mac.prepare_configure_subplots`
    has been replaced by `configure_subplots()`.
-   `backend_pdf.Name.hexify`
-   `backend_pdf.Operator` and `backend_pdf.Op.op` are deprecated in
    favor of a single standard [enum.Enum]{.title-ref} interface on
    [.backend_pdf.Op]{.title-ref}.
-   `backend_pdf.fill`; vendor the code of the similarly named private
    functions if you rely on these functions.
-   `backend_pgf.LatexManager.texcommand` and
    `backend_pgf.LatexManager.latex_header`
-   `backend_pgf.NO_ESCAPE`
-   `backend_pgf.common_texification`
-   `backend_pgf.get_fontspec`
-   `backend_pgf.get_preamble`
-   `backend_pgf.re_mathsep`
-   `backend_pgf.writeln`
-   `backend_ps.convert_psfrags`
-   `backend_ps.quote_ps_string`; vendor the code of the similarly named
    private functions if you rely on it.
-   `backend_qt.qApp`; use `QtWidgets.QApplication.instance()` instead.
-   `backend_svg.escape_attrib`; vendor the code of the similarly named
    private functions if you rely on it.
-   `backend_svg.escape_cdata`; vendor the code of the similarly named
    private functions if you rely on it.
-   `backend_svg.escape_comment`; vendor the code of the similarly named
    private functions if you rely on it.
-   `backend_svg.short_float_fmt`; vendor the code of the similarly
    named private functions if you rely on it.
-   `backend_svg.generate_transform` and `backend_svg.generate_css`
-   `backend_tk.NavigationToolbar2Tk.lastrect` and
    `backend_tk.RubberbandTk.lastrect`
-   `backend_tk.NavigationToolbar2Tk.window`; use `toolbar.master`
    instead.
-   `backend_tools.ToolBase.destroy`; To run code upon tool removal,
    connect to the `tool_removed_event` event.
-   `backend_wx.RendererWx.offset_text_height`
-   `backend_wx.error_msg_wx`
-   `FigureCanvasBase.pick`; directly call [.Figure.pick]{.title-ref},
    which has taken over the responsibility of checking the canvas
    widget lock as well.
-   `FigureCanvasBase.resize`, which has no effect; use
    `FigureManagerBase.resize` instead.
-   `FigureManagerMac.close`
-   `FigureFrameWx.sizer`; use `frame.GetSizer()` instead.
-   `FigureFrameWx.figmgr` and `FigureFrameWx.get_figure_manager`; use
    `frame.canvas.manager` instead.
-   `FigureFrameWx.num`; use `frame.canvas.manager.num` instead.
-   `FigureFrameWx.toolbar`; use `frame.GetToolBar()` instead.
-   `FigureFrameWx.toolmanager`; use `frame.canvas.manager.toolmanager`
    instead.

## Modules

The modules `matplotlib.afm`, `matplotlib.docstring`,
`matplotlib.fontconfig_pattern`, `matplotlib.tight_bbox`,
`matplotlib.tight_layout`, and `matplotlib.type1font` are considered
internal and public access is deprecated.

## `checkdep_usetex` deprecated

This method was only intended to disable tests in case no latex install
was found. As such, it is considered to be private and for internal use
only.

Please vendor the code if you need this.

## `date_ticker_factory` deprecated

The `date_ticker_factory` method in the [matplotlib.dates]{.title-ref}
module is deprecated. Instead use [\~.AutoDateLocator]{.title-ref} and
[\~.AutoDateFormatter]{.title-ref} for a more flexible and scalable
locator and formatter.

If you need the exact `date_ticker_factory` behavior, please copy the
code.

## `dviread.find_tex_file` will raise `FileNotFoundError`

In the future, `dviread.find_tex_file` will raise a
[FileNotFoundError]{.title-ref} for missing files. Previously, it would
return an empty string in such cases. Raising an exception allows
attaching a user-friendly message instead. During the transition period,
a warning is raised.

## `transforms.Affine2D.identity()`

\... is deprecated in favor of directly calling the
[.Affine2D]{.title-ref} constructor with no arguments.

## Deprecations in `testing.decorators`

The unused class `CleanupTestCase` and decorator `cleanup` are
deprecated and will be removed. Vendor the code, including the private
function `_cleanup_cm`.

The function `check_freetype_version` is considered internal and
deprecated. Vendor the code of the private function
`_check_freetype_version`.

## `text.get_rotation()`

\... is deprecated with no replacement. Copy the original implementation
if needed.

## Miscellaneous internals

-   `axes_grid1.axes_size.AddList`; use `sum(sizes, start=Fixed(0))`
    (for example) to sum multiple size objects.
-   `axes_size.Padded`; use `size + pad` instead
-   `axes_size.SizeFromFunc`, `axes_size.GetExtentHelper`
-   `AxisArtistHelper.delta1` and `AxisArtistHelper.delta2`
-   `axislines.GridHelperBase.new_gridlines` and
    `axislines.Axes.new_gridlines`
-   `cbook.maxdict`; use the standard library `functools.lru_cache`
    instead.
-   `_DummyAxis.dataLim` and `_DummyAxis.viewLim`; use
    `get_data_interval()`, `set_data_interval()`, `get_view_interval()`,
    and `set_view_interval()` instead.
-   `GridSpecBase.get_grid_positions(..., raw=True)`
-   `ImageMagickBase.delay` and `ImageMagickBase.output_args`
-   `MathtextBackend`, `MathtextBackendAgg`, `MathtextBackendPath`,
    `MathTextWarning`
-   `TexManager.get_font_config`; it previously returned an internal
    hashed key for used for caching purposes.
-   `TextToPath.get_texmanager`; directly construct a
    [.texmanager.TexManager]{.title-ref} instead.
-   `ticker.is_close_to_int`; use `math.isclose(x, round(x))` instead.
-   `ticker.is_decade`; use
    `y = numpy.log(x)/numpy.log(base); numpy.isclose(y, numpy.round(y))`
    instead.