API Changes

If updating Matplotlib breaks your scripts, this list may help you figure out what caused the breakage and how to fix it by updating your code.

For API changes in older versions see

Changes for the latest version are listed below. For new features that were added to Matplotlib, see What's new?

API Changes for 3.3.1

Deprecations

Reverted deprecation of num2epoch and epoch2num

These two functions were deprecated in 3.3.0, and did not return an accurate Matplotlib datenum relative to the new Matplotlib epoch handling (get_epoch and rcParams["date.epoch"] (default: '1970-01-01T00:00:00')). This version reverts the deprecation.

Functions epoch2num and dates.julian2num use date.epoch rcParam

Now epoch2num and (undocumented) julian2num return floating point days since get_epoch as set by rcParams["date.epoch"] (default: '1970-01-01T00:00:00'), instead of floating point days since the old epoch of "0000-12-31T00:00:00". If needed, you can translate from the new to old values as old = new + mdates.date2num(np.datetime64('0000-12-31'))

API Changes for 3.3.0

Behaviour changes

Formatter.fix_minus

Formatter.fix_minus now performs hyphen-to-unicode-minus replacement whenever rcParams["axes.unicode_minus"] (default: True) is True; i.e. its behavior matches the one of ScalarFormatter.fix_minus (ScalarFormatter now just inherits that implementation).

This replacement is now used by the format_data_short method of the various builtin formatter classes, which affects the cursor value in the GUI toolbars.

FigureCanvasBase now always has a manager attribute, which may be None

Previously, it did not necessarily have such an attribute. A check for hasattr(figure.canvas, "manager") should now be replaced by figure.canvas.manager is not None (or getattr(figure.canvas, "manager", None) is not None for back-compatibility).

cbook.CallbackRegistry now propagates exceptions when no GUI event loop is running

cbook.CallbackRegistry now defaults to propagating exceptions thrown by callbacks when no interactive GUI event loop is running. If a GUI event loop is running, cbook.CallbackRegistry still defaults to just printing a traceback, as unhandled exceptions can make the program completely abort() in that case.

Axes.locator_params() validates axis parameter

axes.Axes.locator_params used to accept any value for axis and silently did nothing, when passed an unsupported value. It now raises a ValueError.

Axis.set_tick_params() validates which parameter

Axis.set_tick_params (and the higher level axes.Axes.tick_params and pyplot.tick_params) used to accept any value for which and silently did nothing, when passed an unsupported value. It now raises a ValueError.

Axis.set_ticklabels() must match FixedLocator.locs

If an axis is using a ticker.FixedLocator, typically set by a call to Axis.set_ticks, then the number of ticklabels supplied must match the number of locations available (FixedFormattor.locs). If not, a ValueError is raised.

backend_pgf.LatexManager.latex

backend_pgf.LatexManager.latex is now created with encoding="utf-8", so its stdin, stdout, and stderr attributes are utf8-encoded.

pyplot.xticks() and pyplot.yticks()

Previously, passing labels without passing the ticks to either pyplot.xticks and pyplot.yticks would result in

TypeError: object of type 'NoneType' has no len()

It now raises a TypeError with a proper description of the error.

Setting the same property under multiple aliases now raises a TypeError

Previously, calling e.g. plot(..., color=somecolor, c=othercolor) would emit a warning because color and c actually map to the same Artist property. This now raises a TypeError.

FileMovieWriter temporary frames directory

FileMovieWriter now defaults to writing temporary frames in a temporary directory, which is always cleared at exit. In order to keep the individual frames saved on the filesystem, pass an explicit frame_prefix.

Axes.plot no longer accepts x and y being both 2D and with different numbers of columns

Previously, calling Axes.plot e.g. with x of shape (n, 3) and y of shape (n, 2) would plot the first column of x against the first column of y, the second column of x against the second column of y, and the first column of x against the third column of y. This now raises an error instead.

Text.update_from now copies usetex state from the source Text

stem now defaults to use_line_collection=True

This creates the stem plot as a LineCollection rather than individual Line2D objects, greatly improving performance.

rcParams color validator is now stricter

Previously, rcParams entries whose values were color-like accepted "spurious" extra letters or characters in the "middle" of the string, e.g. "(0, 1a, '0.5')" would be interpreted as (0, 1, 0.5). These extra characters (including the internal quotes) now cause a ValueError to be raised.

SymLogNorm now has a base parameter

Previously, SymLogNorm had no base keyword argument, and defaulted to base=np.e whereas the documentation said it was base=10. In preparation to make the default 10, calling SymLogNorm without the new base keyword argument emits a deprecation warning.

errorbar now color cycles when only errorbar color is set

Previously setting the ecolor would turn off automatic color cycling for the plot, leading to the the lines and markers defaulting to whatever the first color in the color cycle was in the case of multiple plot calls.

rcsetup.validate_color_for_prop_cycle now always raises TypeError for bytes input

It previously raised TypeError, except when the input was of the form b"C[number]" in which case it raised a ValueError.

FigureCanvasPS.print_ps and FigureCanvasPS.print_eps no longer apply edgecolor and facecolor

These methods now assume that the figure edge and facecolor have been correctly applied by FigureCanvasBase.print_figure, as they are normally called through it.

This behavior is consistent with other figure saving methods (FigureCanvasAgg.print_png, FigureCanvasPdf.print_pdf, FigureCanvasSVG.print_svg).

pyplot.subplot() now raises TypeError when given an incorrect number of arguments

This is consistent with other signature mismatch errors. Previously a ValueError was raised.

Shortcut for closing all figures

Shortcuts for closing all figures now also work for the classic toolbar. There is no default shortcut any more because unintentionally closing all figures by a key press might happen too easily. You can configure the shortcut yourself using rcParams["keymap.quit_all"] (default: []).

Autoscale for arrow

Calling ax.arrow() will now autoscale the axes.

set_tick_params(label1On=False) now also makes the offset text (if any) invisible

... because the offset text can rarely be interpreted without tick labels anyways.

Axes.annotate and pyplot.annotate parameter name changed

The parameter s to Axes.annotate and pyplot.annotate is renamed to text, matching Annotation.

The old parameter name remains supported, but support for it will be dropped in a future Matplotlib release.

font_manager.json_dump now locks the font manager dump file

... to prevent multiple processes from writing to it at the same time.

pyplot.rgrids and pyplot.thetagrids now act as setters also when called with only kwargs

Previously, keyword arguments were silently ignored when no positional arguments were given.

Axis.get_minorticklabels and Axis.get_majorticklabels now returns plain list

Previously, Axis.get_minorticklabels and Axis.get_majorticklabels returns silent_list. Their return type is now changed to normal list. get_xminorticklabels, get_yminorticklabels, get_zminorticklabels, Axis.get_ticklabels, get_xmajorticklabels, get_ymajorticklabels and get_zmajorticklabels methods will be affected by this change.

Default slider formatter

The default method used to format Slider values has been changed to use a ScalarFormatter adapted the slider values limits. This should ensure that values are displayed with an appropriate number of significant digits even if they are much smaller or much bigger than 1. To restore the old behavior, explicitly pass a "%1.2f" as the valfmt parameter to Slider.

Add normalize keyword argument to Axes.pie

pie() used to draw a partial pie if the sum of the values was < 1. This behavior is deprecated and will change to always normalizing the values to a full pie by default. If you want to draw a partial pie, please pass normalize=False explicitly.

table.CustomCell is now an alias for table.Cell

All the functionality of CustomCell has been moved to its base class Cell.

wx Timer interval

Setting the timer interval on a not-yet-started TimerWx won't start it anymore.

"step"-type histograms default to the zorder of Line2D

This ensures that they go above gridlines by default. The old zorder can be kept by passing it as a keyword argument to Axes.hist.

Legend and OffsetBox visibility

Legend and OffsetBox subclasses (PaddedBox, AnchoredOffsetbox, and AnnotationBbox) no longer directly keep track of the visibility of their underlying Patch artist, but instead pass that flag down to the Patch.

Legend and Table no longer allow invalid locations

This affects legends produced on an Axes (Axes.legend and pyplot.legend) and on a Figure (Figure.legend and pyplot.figlegend). Figure legends also no longer accept the unsupported 'best' location. Previously, invalid Axes locations would use 'best' and invalid Figure locations would used 'upper right'.

Passing Line2D's drawstyle together with linestyle is removed

Instead of plt.plot(..., linestyle="steps--"), use plt.plot(..., linestyle="--", drawstyle="steps"). ds is also an alias for drawstyle.

Upper case color strings

Support for passing single-letter colors (one of "rgbcmykw") as UPPERCASE characters is removed; these colors are now case-sensitive (lowercase).

tight/constrained_layout no longer worry about titles that are too wide

tight_layout and constrained_layout shrink axes to accommodate "decorations" on the axes. However, if an xlabel or title is too long in the x direction, making the axes smaller in the x-direction doesn't help. The behavior of both has been changed to ignore the width of the title and xlabel and the height of the ylabel in the layout logic.

This also means there is a new keyword argument for axes.Axes.get_tightbbox and axis.Axis.get_tightbbox: for_layout_only, which defaults to False, but if True returns a bounding box using the rules above.

rcParams["savefig.facecolor"] (default: 'auto') and rcParams["savefig.edgecolor"] (default: 'auto') now default to "auto"

This newly allowed value for rcParams["savefig.facecolor"] (default: 'auto') and rcParams["savefig.edgecolor"] (default: 'auto'), as well as the facecolor and edgecolor parameters to Figure.savefig, means "use whatever facecolor and edgecolor the figure current has".

When using a single dataset, Axes.hist no longer wraps the added artist in a silent_list

When Axes.hist is called with a single dataset, it adds to the axes either a BarContainer object (when histtype="bar" or "barstacked"), or a Polygon object (when histype="step" or "stepfilled") -- the latter being wrapped in a list-of-one-element. Previously, either artist would be wrapped in a silent_list. This is no longer the case: the BarContainer is now returned as is (this is an API breaking change if you were directly relying on the concrete list API; however, BarContainer inherits from tuple so most common operations remain available), and the list-of-one Polygon is returned as is. This makes the repr of the returned artist more accurate: it is now

<BarContainer object of of 10 artists>  # "bar", "barstacked"
[<matplotlib.patches.Polygon object at 0xdeadbeef>]  # "step", "stepfilled"

instead of

<a list of 10 Patch objects>  # "bar", "barstacked"
<a list of 1 Patch objects>  # "step", "stepfilled"

When Axes.hist is called with multiple artists, it still wraps its return value in a silent_list, but uses more accurate type information

<a list of 3 BarContainer objects>  # "bar", "barstacked"
<a list of 3 List[Polygon] objects>  # "step", "stepfilled"

instead of

<a list of 3 Lists of Patches objects>  # "bar", "barstacked"
<a list of 3 Lists of Patches objects>  # "step", "stepfilled"

Qt and wx backends no longer create a status bar by default

The coordinates information is now displayed in the toolbar, consistently with the other backends. This is intended to simplify embedding of Matplotlib in larger GUIs, where Matplotlib may control the toolbar but not the status bar.

rcParams["text.hinting"] (default: 'force_autohint') now supports names mapping to FreeType flags

rcParams["text.hinting"] (default: 'force_autohint') now supports the values "default", "no_autohint", "force_autohint", and "no_hinting", which directly map to the FreeType flags FT_LOAD_DEFAULT, etc. The old synonyms (respectively "either", "native", "auto", and "none") are still supported, but their use is discouraged. To get normalized values, use backend_agg.get_hinting_flag, which returns integer flag values.

cbook.get_sample_data auto-loads numpy arrays

When cbook.get_sample_data is used to load a npy or npz file and the keyword-only parameter np_load is True, the file is automatically loaded using numpy.load. np_load defaults to False for backwards compatibility, but will become True in a later release.

get_text_width_height_descent now checks ismath rather than rcParams["text.usetex"] (default: False)

... to determine whether a string should be passed to the usetex machinery or not. This allows single strings to be marked as not-usetex even when the rcParam is True.

Axes.vlines, Axes.hlines, pyplot.vlines and pyplot.hlines colors parameter default change

The colors parameter will now default to rcParams["lines.color"] (default: 'C0'), while previously it defaulted to 'k'.

Aggressively autoscale clim in ScalerMappable classes

Previously some plotting methods would defer autoscaling until the first draw if only one of the vmin or vmax keyword arguments were passed (Axes.scatter, Axes.hexbin, Axes.imshow, Axes.pcolorfast) but would scale based on the passed data if neither was passed (independent of the norm keyword arguments). Other methods (Axes.pcolor, Axes.pcolormesh) always autoscaled base on the initial data.

All of the plotting methods now resolve the unset vmin or vmax at the initial call time using the data passed in.

If you were relying on exactly one of the vmin or vmax remaining unset between the time when the method is called and the first time the figure is rendered you get back the old behavior by manually setting the relevant limit back to None

cm_obj.norm.vmin = None
# or
cm_obj.norm.vmax = None

which will be resolved during the draw process.

Deprecations

figure.add_axes() without arguments

Calling fig.add_axes() with no arguments currently does nothing. This call will raise an error in the future. Adding a free-floating axes needs a position rectangle. If you want a figure-filling single axes, use add_subplot() instead.

backend_wx.DEBUG_MSG

backend_wx.DEBUG_MSG is deprecated. The wx backends now use regular logging.

Colorbar.config_axis()

Colorbar.config_axis() is considered internal. Its use is deprecated.

NonUniformImage.is_grayscale and PcolorImage.is_grayscale

These attributes are deprecated, for consistency with AxesImage.is_grayscale, which was removed back in Matplotlib 2.0.0. (Note that previously, these attributes were only available after rendering the image).

den parameter and attribute to mpl_toolkits.axisartist.angle_helper

For all locator classes defined in mpl_toolkits.axisartist.angle_helper, the den parameter has been renamed to nbins, and the den attribute deprecated in favor of its (preexisting) synonym nbins, for consistency with locator classes defined in matplotlib.ticker.

backend_pgf.LatexManager.latex_stdin_utf8

backend_pgf.LatexManager.latex is now created with encoding="utf-8", so its stdin attribute is already utf8-encoded; the latex_stdin_utf8 attribute is thus deprecated.

Flags containing "U" passed to cbook.to_filehandle and cbook.open_file_cm

Please remove "U" from flags passed to cbook.to_filehandle and cbook.open_file_cm. This is consistent with their removal from open in Python 3.9.

PDF and PS character tracking internals

The used_characters attribute and track_characters and merge_used_characters methods of RendererPdf, PdfFile, and RendererPS are deprecated.

Case-insensitive capstyles and joinstyles

Please pass capstyles ("miter", "round", "bevel") and joinstyles ("butt", "round", "projecting") as lowercase.

Passing raw data to register_cmap()

Passing raw data via parameters data and lut to register_cmap() is deprecated. Instead, explicitly create a LinearSegmentedColormap and pass it via the cmap parameter: register_cmap(cmap=LinearSegmentedColormap(name, data, lut)).

DateFormatter.illegal_s

This attribute is unused and deprecated.

widgets.TextBox.params_to_disable

This attribute is deprecated.

Revert deprecation *min, *max keyword arguments to set_x/y/zlim_3d()

These keyword arguments were deprecated in 3.0, alongside with the respective parameters in set_xlim() / set_ylim(). The deprecations of the 2D versions were already reverted in in 3.1.

cbook.local_over_kwdict

This function is deprecated. Use cbook.normalize_kwargs instead.

Passing both singular and plural colors, linewidths, linestyles to Axes.eventplot

Passing e.g. both linewidth and linewidths will raise a TypeError in the future.

Setting rcParams["text.latex.preamble"] (default: '') or rcParams["pdf.preamble"] to non-strings

These rcParams should be set to string values. Support for None (meaning the empty string) and lists of strings (implicitly joined with newlines) is deprecated.

Parameters norm and vmin/vmax should not be used simultaneously

Passing parameters norm and vmin/vmax simultaneously to functions using colormapping such as scatter() and imshow() is deprecated. Inestead of norm=LogNorm(), vmin=min_val, vmax=max_val pass norm=LogNorm(min_val, max_val). vmin and vmax should only be used without setting norm.

Effectless parameters of Figure.colorbar and matplotlib.colorbar.Colorbar

The cmap and norm parameters of Figure.colorbar and matplotlib.colorbar.Colorbar have no effect because they are always overridden by the mappable's colormap and norm; they are thus deprecated. Likewise, passing the alpha, boundaries, values, extend, or filled parameters with a ContourSet mappable, or the alpha parameter with an Artist mappable, is deprecated, as the mappable would likewise override them.

args_key and exec_key attributes of builtin MovieWriters

These attributes are deprecated.

Unused parameters

The following parameters do not have any effect and are deprecated:

Passing props to Shadow

The parameter props of Shadow is deprecated. Use keyword arguments instead.

Axes.update_datalim_bounds

This method is deprecated. Use ax.dataLim.set(Bbox.union([ax.dataLim, bounds])) instead.

{,Symmetrical}LogScale.{,Inverted}LogTransform

LogScale.LogTransform, LogScale.InvertedLogTransform, SymmetricalScale.SymmetricalTransform and SymmetricalScale.InvertedSymmetricalTransform are deprecated. Directly access the transform classes from the scale module.

TexManager.cachedir, TexManager.rgba_arrayd

Use matplotlib.get_cachedir() instead for the former; there is no replacement for the latter.

Setting Line2D's pickradius via Line2D.set_picker

Setting a Line2D's pickradius (i.e. the tolerance for pick events and containment checks) via Line2D.set_picker is deprecated. Use Line2D.set_pickradius instead.

Line2D.set_picker no longer sets the artist's custom-contain() check.

Artist.set_contains, Artist.get_contains

Setting a custom method overriding Artist.contains is deprecated. There is no replacement, but you may still customize pick events using Artist.set_picker.

Colorbar methods

The on_mappable_changed and update_bruteforce methods of Colorbar are deprecated; both can be replaced by calls to update_normal.

OldScalarFormatter, IndexFormatter and DateIndexFormatter

These formatters are deprecated. Their functionality can be implemented using e.g. FuncFormatter.

OldAutoLocator

This ticker is deprecated.

required, forbidden and allowed parameters of cbook.normalize_kwargs

These parameters are deprecated.

The TTFPATH and AFMPATH environment variables

Support for the (undocumented) TTFPATH and AFMPATH environment variables is deprecated. Additional fonts may be registered using matplotlib.font_manager.fontManager.addfont().

matplotlib.compat

This module is deprecated.

matplotlib.backends.qt_editor.formsubplottool

This module is deprecated. Use matplotlib.backends.backend_qt5.SubplotToolQt instead.

AVConv animation writer deprecated

The AVConvBase, AVConvWriter and AVConvFileWriter classes, and the associated animation.avconv_path and animation.avconv_args rcParams are deprecated.

Debian 8 (2015, EOL 06/2020) and Ubuntu 14.04 (EOL 04/2019) were the last versions of Debian and Ubuntu to ship avconv. It remains possible to force the use of avconv by using the ffmpeg-based writers with rcParams["animation.ffmpeg_path"] (default: 'ffmpeg') set to "avconv".

log/symlog scale base, ticks, and nonpos specification

semilogx, semilogy, loglog, LogScale, and SymmetricalLogScale used to take keyword arguments that depends on the axis orientation ("basex" vs "basey", "subsx" vs "subsy", "nonposx" vs "nonposy"); these parameter names are now deprecated in favor of "base", "subs", "nonpositive". This deprecation also affects e.g. ax.set_yscale("log", basey=...) which must now be spelled ax.set_yscale("log", base=...).

The change from "nonpos" to "nonpositive" also affects LogTransform, InvertedLogTransform, SymmetricalLogTransform, etc.

To use different bases for the x-axis and y-axis of a loglog plot, use e.g. ax.set_xscale("log", base=10); ax.set_yscale("log", base=2).

DraggableBase.artist_picker

This method is deprecated. If you previously reimplemented it in a subclass, set the artist's picker instead with Artist.set_picker.

clear_temp parameter and attribute of FileMovieWriter

The clear_temp parameter and attribute of FileMovieWriter is deprecated. In the future, files placed in a temporary directory (using frame_prefix=None, the default) will be cleared; files placed elsewhere will not.

Deprecated rcParams validators

The following validators, defined in rcsetup, are deprecated: validate_fontset, validate_mathtext_default, validate_alignment, validate_svg_fontset, validate_pgf_texsystem, validate_movie_frame_fmt, validate_axis_locator, validate_movie_html_fmt, validate_grid_axis, validate_axes_titlelocation, validate_toolbar, validate_ps_papersize, validate_legend_loc, validate_bool_maybe_none, validate_hinting, validate_movie_writers, validate_webagg_address, validate_nseq_float, validate_nseq_int. To test whether an rcParam value would be acceptable, one can test e.g. rc = RcParams(); rc[k] = v raises an exception.

Stricter rcParam validation

rcParams["axes.axisbelow"] (default: 'line') currently normalizes all strings starting with "line" (case-insensitive) to the option "line". This is deprecated; in a future version only the exact string "line" (case-sensitive) will be supported.

add_subplot() validates its inputs

In particular, for add_subplot(rows, cols, index), all parameters must be integral. Previously strings and floats were accepted and converted to int. This will now emit a deprecation warning.

Toggling axes navigation from the keyboard using "a" and digit keys

Axes navigation can still be toggled programmatically using Axes.set_navigate.

The following related APIs are also deprecated: backend_tools.ToolEnableAllNavigation, backend_tools.ToolEnableNavigation, and rcParams["keymap.all_axes"].

matplotlib.test(recursionlimit=...)

The recursionlimit parameter of matplotlib.test is deprecated.

mathtext glues

The copy parameter of mathtext.Glue is deprecated (the underlying glue spec is now immutable). mathtext.GlueSpec is deprecated.

Signatures of Artist.draw and Axes.draw

The inframe parameter to Axes.draw is deprecated. Use Axes.redraw_in_frame instead.

Not passing the renderer parameter to Axes.draw is deprecated. Use axes.draw_artist(axes) instead.

These changes make the signature of the draw (artist.draw(renderer)) method consistent across all artists; thus, additional parameters to Artist.draw are deprecated.

DraggableBase.on_motion_blit

This method is deprecated. DraggableBase.on_motion now handles both the blitting and the non-blitting cases.

Passing the dash offset as None

Fine control of dash patterns can be achieved by passing an (offset, (on-length, off-length, on-length, off-length, ...)) pair as the linestyle property of Line2D and LineCollection. Previously, certain APIs would accept offset = None as a synonym for offset = 0, but this was never universally implemented, e.g. for vector output. Support for offset = None is deprecated, set the offset to 0 instead.

RendererCairo.fontweights, RendererCairo.fontangles

... are deprecated.

autofmt_xdate(which=None)

This is deprecated, use its more explicit synonym, which="major", instead.

JPEG options

The quality, optimize, and progressive keyword arguments to savefig, which were only used when saving to JPEG, are deprecated. rcParams["savefig.jpeg_quality"] (default: 95) is likewise deprecated.

Such options should now be directly passed to Pillow using savefig(..., pil_kwargs={"quality": ..., "optimize": ..., "progressive": ...}).

dviread.Encoding

This class was (mostly) broken and is deprecated.

Axis and Locator pan and zoom

The unused pan and zoom methods of Axis and Locator are deprecated. Panning and zooming are now implemented using the start_pan, drag_pan, and end_pan methods of Axes.

Passing None to various Axes subclass factories

Support for passing None as base class to axes.subplot_class_factory, axes_grid1.parasite_axes.host_axes_class_factory, axes_grid1.parasite_axes.host_subplot_class_factory, axes_grid1.parasite_axes.parasite_axes_class_factory, and axes_grid1.parasite_axes.parasite_axes_auxtrans_class_factory is deprecated. Explicitly pass the correct base Axes class instead.

axes_rgb

In mpl_toolkits.axes_grid1.axes_rgb, imshow_rgb is deprecated (use ax.imshow(np.dstack([r, g, b])) instead); RGBAxesBase is deprecated (use RGBAxes instead); RGBAxes.add_RGB_to_figure is deprecated (it was an internal helper).

Substitution.from_params

This method is deprecated. If needed, directly assign to the params attribute of the Substitution object.

PGF backend cleanups

The dummy parameter of RendererPgf is deprecated.

GraphicsContextPgf is deprecated (use GraphicsContextBase instead).

set_factor method of mpl_toolkits.axisartist locators

The set_factor method of mpl_toolkits.axisartist locators (which are different from "standard" Matplotlib tick locators) is deprecated.

widgets.SubplotTool callbacks and axes

The funcleft, funcright, funcbottom, functop, funcwspace, and funchspace methods of widgets.SubplotTool are deprecated.

The axleft, axright, axbottom, axtop, axwspace, and axhspace attributes of widgets.SubplotTool are deprecated. Access the ax attribute of the corresponding slider, if needed.

mathtext Glue helper classes

The Fil, Fill, Filll, NegFil, NegFill, NegFilll, and SsGlue classes in the matplotlib.mathtext module are deprecated. As an alternative, directly construct glue instances with Glue("fil"), etc.

FigureCanvasGTK3._renderer_init

Overriding this method to initialize renderers for GTK3 canvases is deprecated. Instead, the renderer should be initialized in the __init__ method of the subclass (which should call the base-class' __init__ as appropriate). To keep back-compatibility with earlier versions of Matplotlib (which required _renderer_init to be overridden), a fully empty implementation (def _renderer_init(self): pass) may be kept and will not trigger the deprecation warning.

Path helpers in bezier

bezier.make_path_regular is deprecated. Use Path.cleaned() (or Path.cleaned(curves=True), etc.) instead (but note that these methods add a STOP code at the end of the path).

bezier.concatenate_paths is deprecated. Use Path.make_compound_path() instead.

animation.html_args rcParam

The unused animation.html_args rcParam and animation.HTMLWriter.args_key attribute are deprecated.

text.latex.preview rcParam

This rcParam, which controlled the use of the preview.sty LaTeX package to align TeX string baselines, is deprecated, as Matplotlib's own dvi parser now computes baselines just as well as preview.sty.

SubplotSpec.get_rows_columns

This method is deprecated. Use the GridSpec.nrows, GridSpec.ncols, SubplotSpec.rowspan, and SubplotSpec.colspan properties instead.

Qt4-based backends

The qt4agg and qt4cairo backends are deprecated. Qt4 has reached its end-of-life in 2015 and there are no releases for recent versions of Python. Please consider switching to Qt5.

fontdict and minor parameters of Axes.set_xticklabels and Axes.set_yticklabels will become keyword-only

All parameters of Figure.subplots except nrows and ncols will become keyword-only

This avoids typing e.g. subplots(1, 1, 1) when meaning subplot(1, 1, 1), but actually getting subplots(1, 1, sharex=1).

RendererWx.get_gc

This method is deprecated. Access the gc attribute directly instead.

add_all parameter in axes_grid

The add_all parameter of axes_grid1.axes_grid.Grid, axes_grid1.axes_grid.ImageGrid, axes_grid1.axes_rgb.make_rgb_axes and axes_grid1.axes_rgb.RGBAxes is deprecated. Axes are now always added to the parent figure, though they can be later removed with ax.remove().

BboxBase.inverse_transformed

.BboxBase.inverse_transformed is deprecated (call BboxBase.transformed on the inverted() transform instead).

orientation of eventplot() and EventCollection

Setting the orientation of an eventplot() or EventCollection to "none" or None is deprecated; set it to "horizontal" instead. Moreover, the two orientations ("horizontal" and "vertical") will become case-sensitive in the future.

minor kwarg to Axis.get_ticklocs will become keyword-only

Passing this argument positionally is deprecated.

Case-insensitive properties

Normalization of upper or mixed-case property names to lowercase in Artist.set and Artist.update is deprecated. In the future, property names will be passed as is, allowing one to pass names such as patchA or UVC.

ContourSet.ax, Quiver.ax

These attributes are deprecated in favor of ContourSet.axes and Quiver.axes, for consistency with other artists.

Locator.refresh() and associated methods

Locator.refresh() is deprecated. This method was called at certain places to let locators update their internal state, typically based on the axis limits. Locators should now always consult the axis limits when called, if needed.

The associated helper methods NavigationToolbar2.draw() and ToolViewsPositions.refresh_locators() are deprecated, and should be replaced by calls to draw_idle() on the corresponding canvas.

ScalarMappable checkers

The add_checker and check_update methods and update_dict attribute of ScalarMappable are deprecated.

pyplot.tight_layout and ColorbarBase parameters will become keyword-only

All parameters of pyplot.tight_layout and all parameters of ColorbarBase except for the first (ax) will become keyword-only, consistently with Figure.tight_layout and Colorbar, respectively.

Axes.pie radius and startangle

Passing None as either the radius or startangle of an Axes.pie is deprecated; use the explicit defaults of 1 and 0, respectively, instead.

AxisArtist.dpi_transform

... is deprecated. Scale Figure.dpi_scale_trans by 1/72 to achieve the same effect.

offset_position property of Collection

The offset_position property of Collection is deprecated. In the future, Collections will always behave as if offset_position is set to "screen" (the default).

Support for passing offset_position="data" to the draw_path_collection of all renderer classes is deprecated.

transforms.AffineDeltaTransform can be used as a replacement. This API is experimental and may change in the future.

testing.compare.make_external_conversion_command

... is deprecated.

epoch2num and num2epoch are deprecated

These are unused and can be easily reproduced by other date tools. get_epoch will return Matplotlib's epoch.

axes_grid1.CbarAxes attributes

The cbid and locator attribute are deprecated. Use mappable.colorbar_cid and colorbar.locator, as for standard colorbars.

qt_compat.is_pyqt5

This function is deprecated in prevision of the future release of PyQt6. The Qt version can be checked using QtCore.qVersion().

Reordering of parameters by Artist.set

In a future version, Artist.set will apply artist properties in the order in which they are given. This only affects the interaction between the color, edgecolor, facecolor, and, for Collections, alpha properties: the color property now needs to be passed first in order not to override the other properties. This is consistent with e.g. Artist.update, which did not reorder the properties passed to it.

Passing multiple keys as a single comma-separated string or multiple arguments to ToolManager.update_keymap

This is deprecated; pass keys as a list of strings instead.

Statusbar classes and attributes

The statusbar attribute of FigureManagerBase, StatusbarBase and all its subclasses, and StatusBarWx, are deprecated, as messages are now displayed in the toolbar instead.

ismath parameter of draw_tex

The ismath parameter of the draw_tex method of all renderer classes is deprecated (as a call to draw_tex -- not to be confused with draw_text! -- means that the entire string should be passed to the usetex machinery anyways). Likewise, the text machinery will no longer pass the ismath parameter when calling draw_tex (this should only matter for backend implementers).

Passing ismath="TeX!" to RendererAgg.get_text_width_height_descent is deprecated. Pass ismath="TeX" instead, consistently with other low-level APIs which support the values True, False, and "TeX" for ismath.

matplotlib.ttconv

This module is deprecated.

Stricter PDF metadata keys in PGF

Saving metadata in PDF with the PGF backend currently normalizes all keys to lowercase, unlike the PDF backend, which only accepts the canonical case. This is deprecated; in a future version, only the canonically cased keys listed in the PDF specification (and the PdfPages documentation) will be accepted.

Qt modifier keys

The MODIFIER_KEYS, SUPER, ALT, CTRL, and SHIFT global variables of the matplotlib.backends.backend_qt4agg, matplotlib.backends.backend_qt4cairo, matplotlib.backends.backend_qt5agg and matplotlib.backends.backend_qt5cairo modules are deprecated.

TexManager

The TexManager.serif, TexManager.sans_serif, TexManager.cursive and TexManager.monospace attributes are deprecated.

Removals

The following deprecated APIs have been removed:

Modules

  • backends.qt_editor.formlayout (use the formlayout module available on PyPI instead).

Classes, methods and attributes

  • artist.Artist.aname property (no replacement)
  • axis.Axis.iter_ticks (no replacement)
  • Support for custom backends that do not provide a backend_bases.GraphicsContextBase.set_hatch_color method
  • backend_bases.RendererBase.strip_math() (use cbook.strip_math() instead)
  • backend_wx.debug_on_error() (no replacement)
  • backend_wx.raise_msg_to_str() (no replacement)
  • backend_wx.fake_stderr (no replacement)
  • backend_wx.MenuButtonWx (no replacement)
  • backend_wx.PrintoutWx (no replacement)
  • _backend_tk.NavigationToolbar2Tk.set_active() (no replacement)
  • backend_ps.PsBackendHelper.gs_exe property (no replacement)
  • backend_ps.PsBackendHelper.gs_version property (no replacement)
  • backend_ps.PsBackendHelper.supports_ps2write property (no replacement)
  • backend_ps.RendererPS.afmfontd property (no replacement)
  • backend_ps.GraphicsContextPS.shouldstroke property (no replacement)
  • backend_gtk3.FileChooserDialog (no replacement)
  • backend_gtk3.SaveFigureGTK3.get_filechooser() (no replacement)
  • backend_gtk3.NavigationToolbar2GTK3.get_filechooser() (no replacement)
  • backend_gtk3cairo.FigureManagerGTK3Cairo (use backend_gtk3.FigureManagerGTK3 instead)
  • backend_pdf.RendererPdf.afm_font_cache property (no replacement)
  • backend_pgf.LatexManagerFactory (no replacement)
  • backend_qt5.NavigationToolbar2QT.buttons property (no replacement)
  • backend_qt5.NavigationToolbar2QT.adj_window property (no replacement)
  • bezier.find_r_to_boundary_of_closedpath() (no replacement)
  • cbook.dedent() (use inspect.cleandoc instead)
  • cbook.get_label() (no replacement)
  • cbook.is_hashable() (use isinstance(..., collections.abc.Hashable) instead)
  • cbook.iterable() (use numpy.iterable() instead)
  • cbook.safezip() (no replacement)
  • colorbar.ColorbarBase.get_cmap (use ScalarMappable.get_cmap instead)
  • colorbar.ColorbarBase.set_cmap (use ScalarMappable.set_cmap instead)
  • colorbar.ColorbarBase.get_clim (use ScalarMappable.get_clim instead)
  • colorbar.ColorbarBase.set_clim (use ScalarMappable.set_clim instead)
  • colorbar.ColorbarBase.set_norm (use ScalarMappable.set_norm instead)
  • dates.seconds() (no replacement)
  • dates.minutes() (no replacement)
  • dates.hours() (no replacement)
  • dates.weeks() (no replacement)
  • dates.strpdate2num and dates.bytespdate2num (use time.strptime or dateutil.parser.parse or dates.datestr2num instead)
  • docstring.Appender (no replacement)
  • docstring.dedent() (use inspect.getdoc instead)
  • docstring.copy_dedent() (use docstring.copy() and inspect.getdoc instead)
  • font_manager.OSXInstalledFonts() (no replacement)
  • image.BboxImage.interp_at_native property (no replacement)
  • lines.Line2D.verticalOffset property (no replacement)
  • matplotlib.checkdep_dvipng (no replacement)
  • matplotlib.checkdep_ghostscript (no replacement)
  • matplotlib.checkdep_pdftops (no replacement)
  • matplotlib.checkdep_inkscape (no replacement)
  • matplotlib.get_py2exe_datafiles (no replacement)
  • matplotlib.tk_window_focus (use rcParams['tk.window_focus'] instead)
  • mlab.demean() (use mlab.detrend_mean() instead)
  • path.get_paths_extents() (use path.get_path_collection_extents() instead)
  • path.Path.has_nonfinite() (use not np.isfinite(self.vertices).all() instead)
  • projections.process_projection_requirements() (no replacement)
  • pyplot.plotfile() (Instead, load the data using pandas.read_csv or numpy.loadtxt or similar and use regular pyplot functions to plot the loaded data.)
  • quiver.Quiver.color() (use Quiver.get_facecolor() instead)
  • quiver.Quiver.keyvec property (no replacement)
  • quiver.Quiver.keytext property (no replacement)
  • rcsetup.validate_qt4() (no replacement)
  • rcsetup.validate_qt5() (no replacement)
  • rcsetup.validate_verbose() (no replacement)
  • rcsetup.ValidateInterval (no replacement)
  • scale.LogTransformBase (use scale.LogTransform instead)
  • scale.InvertedLogTransformBase (use scale.InvertedLogTransform instead)
  • scale.Log10Transform (use scale.LogTransform instead)
  • scale.InvertedLog10Transform (use scale.InvertedLogTransform instead)
  • scale.Log2Transform (use scale.LogTransform instead)
  • scale.InvertedLog2Transform (use scale.InvertedLogTransform instead)
  • scale.NaturalLogTransform (use scale.LogTransform instead)
  • scale.InvertedNaturalLogTransform (use scale.InvertedLogTransform instead)
  • scale.get_scale_docs() (no replacement)
  • sphinxext.plot_directive.plot_directive() (use the class PlotDirective instead)
  • sphinxext.mathmpl.math_directive() (use the class MathDirective instead)
  • spines.Spine.is_frame_like() (no replacement)
  • testing.decorators.switch_backend() (use @pytest.mark.backend decorator instead)
  • text.Text.is_math_text() (use cbook.is_math_text() instead)
  • text.TextWithDash() (use text.Annotation instead)
  • textpath.TextPath.is_math_text() (use cbook.is_math_text() instead)
  • textpath.TextPath.text_get_vertices_codes() (use textpath.text_to_path.get_text_path() instead)
  • textpath.TextToPath.glyph_to_path() (use font.get_path() and manual translation of the vertices instead)
  • ticker.OldScalarFormatter.pprint_val() (no replacement)
  • ticker.ScalarFormatter.pprint_val() (no replacement)
  • ticker.LogFormatter.pprint_val() (no replacement)
  • ticker.decade_down() (no replacement)
  • ticker.decade_up() (no replacement)
  • Tick properties gridOn, tick1On, tick2On, label1On, label2On (use set_visible() / get_visible() on Tick.gridline, Tick.tick1line, Tick.tick2line, Tick.label1, Tick.label2 instead)
  • widgets.SpanSelector.buttonDown property (no replacement)
  • mplot3d.proj3d.line2d() (no replacement)
  • mplot3d.proj3d.line2d_dist() (no replacement)
  • mplot3d.proj3d.line2d_seg_dist() (no replacement)
  • mplot3d.proj3d.mod() (use numpy.linalg.norm instead)
  • mplot3d.proj3d.proj_transform_vec() (no replacement)
  • mplot3d.proj3d.proj_transform_vec_clip() (no replacement)
  • mplot3d.proj3d.vec_pad_ones() (no replacement)
  • mplot3d.proj3d.proj_trans_clip_points() (no replacement)
  • mplot3d.art3d.norm_angle() (no replacement)
  • mplot3d.art3d.norm_text_angle() (no replacement)
  • mplot3d.art3d.path_to_3d_segment() (no replacement)
  • mplot3d.art3d.paths_to_3d_segments() (no replacement)
  • mplot3d.art3d.path_to_3d_segment_with_codes() (no replacement)
  • mplot3d.art3d.paths_to_3d_segments_with_codes() (no replacement)
  • mplot3d.art3d.get_patch_verts() (no replacement)
  • mplot3d.art3d.get_colors() (no replacement)
  • mplot3d.art3d.zalpha() (no replacement)
  • mplot3d.axis3d.get_flip_min_max() (no replacement)
  • mplot3d.axis3d.Axis.get_tick_positions() (no replacement)
  • axisartist.axis_artist.UnimplementedException (no replacement)
  • axisartist.axislines.SimpleChainedObjects (use axis_grid1.mpl_axes.SimpleChainedObjects instead)
  • axisartist.axislines.Axes.AxisDict (use axis_grid1.mpl_axes.Axes.AxisDict instead)

Arguments

  • Axes.text() / pyplot.text() do not support the parameter withdash anymore. Use Axes.annotate() and pyplot.annotate() instead.
  • The first parameter of matplotlib.use has been renamed from arg to backend (only relevant if you pass by keyword).
  • The parameter warn of matplotlib.use has been removed. A failure to switch the backend will now always raise an ImportError if force is set; catch that error if necessary.
  • All parameters of matplotlib.use except the first one are now keyword-only.
  • The unused parameters shape and imlim of imshow() are now removed. All parameters beyond extent are now keyword-only.
  • The unused parameter interp_at_native of BboxImage has been removed.
  • The parameter usetex of TextToPath.get_text_path has been removed. Use ismath='TeX' instead.
  • The parameter block of show() is now keyword-only, and arbitrary arguments or keyword arguments are no longer accepted.
  • The parameter frameon of Figure.savefig has been removed. Use facecolor="none" to get a transparent background.
  • Passing a wx.EvtHandler as the first argument to backend_wx.TimerWx is not supported anymore; the signature of TimerWx is now consistent with TimerBase.
  • The manage_xticks parameter of boxplot and bxp has been renamed to manage_ticks.
  • The normed parameter of hist2d has been renamed to density.
  • The s parameter of Annotation has been renamed to text.
  • For all functions in bezier that supported a tolerence parameter, this parameter has been renamed to tolerance.
  • axis("normal") is not supported anymore. Use the equivalent axis("auto") instead.
  • axis() does not accept arbitrary keyword arguments anymore.
  • Axis.set_ticklabels() does not accept arbitrary positional arguments other than ticklabels.
  • mpl_toolkits.mplot3d.art3d.Poly3DCollection.set_zsort does not accept the value True anymore. Pass the equivalent value 'average' instead.
  • AnchoredText no longer accepts horizontalalignment or verticalalignment keyword arguments.
  • ConnectionPatch no longer accepts the arrow_transmuter and connector keyword arguments, which did nothing since 3.0.
  • FancyArrowPatch no longer accepts the arrow_transmuter and connector keyword arguments, which did nothing since 3.0.
  • TextPath no longer accepts arbitrary positional or keyword arguments.
  • MaxNLocator.set_params() no longer accepts arbitrary keyword arguments.
  • pie no longer accepts and squeezes non-1D inputs; pass 1D input to the x argument.
  • Passing (n, 1)-shaped error arrays to Axes.errorbar() is no longer supported; pass a 1D array instead.

rcParams

  • The text.latex.unicode rcParam has been removed, with no replacement. Matplotlib now always supports unicode in usetex.
  • The savefig.frameon rcParam has been removed. Set rcParams["savefig.facecolor"] (default: 'auto') to "none" to get a transparent background.
  • The pgf.debug, verbose.fileo and verbose.verbose.level rcParams, which had no effect, have been removed.
  • Support for setting rcParams["mathtext.default"] (default: 'it') to "circled" has been removed.

Environment variables

  • MATPLOTLIBDATA (no replacement).

mathtext

  • The \stackrel command (which behaved differently from its LaTeX version) has been removed. Use \genfrac instead.
  • The \mathcircled command has been removed. Directly use Unicode characters, such as '\N{CIRCLED LATIN CAPITAL LETTER A}', instead.

Development changes

Matplotlib now requires numpy>=1.15

Matplotlib now uses Pillow to save and read pngs

The builtin png encoder and decoder has been removed, and Pillow is now a dependency. Note that when reading 16-bit RGB(A) images, Pillow truncates them to 8-bit precision, whereas the old builtin decoder kept the full precision.

The deprecated wx backend (not wxagg!) now always uses wx's builtin jpeg and tiff support rather than relying on Pillow for writing these formats; this behavior is consistent with wx's png output.