You are reading documentation for the unreleased version of Matplotlib. Try searching for the released version of this page instead?
Applications are open for the 2018 John Hunter Matplotlib Summer Fellowship. Apply now!
Version 2.2.2.post1772+gd9240e24b
Fork me on GitHub

Table Of Contents

API Changes

A log of changes to the most recent version Matplotlib that affect the utward-facing API. 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 Old API Changes.

For new features that were added to Matplotlib, see What's new in Matplotlib 3.0.

This pages lists API changes for the most recent version of Matplotlib.


The list below is a table of contents of individual files from the 'next_api_changes' folder. When a release is made

  • The full text list below should be moved into its own file in 'prev_api_changes'
  • All the files in 'next_api_changes' should be moved to the bottom of this page
  • This note, and the toctree below should be commented out

API Changes for 3.0.0

Drop support for python 2

Matplotlib 3 only supports python 3.5 and higher

Hold machinery removed

Setting or unsetting hold (deprecated in version 2.1) has now been completely removed. Matplotlib now always behaves as if hold=True. To clear an axes you can manually use cla(), or to clear an entire figure use clf().

Axes.hist2d now uses pcolormesh instead of pcolorfast

Axes.hist2d now uses pcolormesh instead of pcolorfast, which will improve the handling of log-axes. Note that the returned image now is of type QuadMesh instead of AxesImage.

Text.set_text with string argument None sets string to empty

Text.set_text when passed a string value of None would set the string to "None", so subsequent calls to Text.get_text would return the ambiguous "None" string.

This change sets text objects passed None to have empty strings, so that Text.get_text returns and an empty string.


The following modules are deprecated:

  • matplotlib.compat.subprocess. This was a python 2 workaround, but all the functionality can now be found in the python 3 standard library subprocess.
  • matplotlib.backends.wx_compat. Python 3 is only compatible with wxPython 4, so support for wxPython 3 or earlier can be dropped.

The following classes, methods, functions, and attributes are deprecated:

  • RcParams.msg_depr, RcParams.msg_depr_ignore, RcParams.msg_depr_set, RcParams.msg_obsolete, RcParams.msg_backend_obsolete
  • afm.parse_afm
  • backend_pgf.get_texcommand
  • backend_ps.get_bbox
  • backend_qt5.error_msg_qt, backend_qt5.exception_handler
  • backend_wx.FigureCanvasWx.macros
  • cbook.GetRealpathAndStat, cbook.Locked
  • cbook.is_numlike (use isinstance(..., numbers.Number) instead), cbook.listFiles, cbook.unicode_safe
  • container.Container.set_remove_method
  •, .cl_xy, and .cl_cvalues
  • dates.DateFormatter.strftime_pre_1900, dates.DateFormatter.strftime
  • font_manager.TempCache
  • mathtext.unichr_safe (use chr instead)
  • table.Table.get_child_artists (use get_children instead)
  • testing.decorators.CleanupTest testing.decorators.skip_if_command_unavailable
  • FigureCanvasQT.keyAutoRepeat (directly check event.guiEvent.isAutoRepeat() in the event handler to decide whether to handle autorepeated key presses)
  • FigureCanvasWx.macros
  • _ImageBase.iterpnames, use the interpolation_names property instead. (this affects classes that inherit from _ImageBase including FigureImage, BboxImage, and AxesImage)
  • patches.Polygon.xy
  • texmanager.dvipng_hack_alpha
  • text.Annotation.arrow
  • Legend.draggable(), in favor of Legend.set_draggable()
    (Legend.draggable may be reintroduced as a property in future releases)

The following rcParams are deprecated:

  • (use datapath instead)
  • pgf.debug (the pgf backend relies on logging)
  • text.latex.unicode

The following keyword arguments are deprecated:

  • passing verts to Axes.scatter (use marker instead)
  • passing obj_type to cbook.deprecated

The following call signatures are deprecated: - passing a wx.EvtHandler as first argument to backend_wx.TimerWx

Deprecated methods removed from matplotlib.testing

The deprecated methods knownfailureif and remove_text have been removed from matplotlib.testing.decorators.

The entire contents of testing.noseclasses have also been removed.

matplotlib.cbook.deprecation.mplDeprecation is deprecated

matplotlib.cbook.deprecation.mplDeprecation will be removed in future versions. It is just an alias for matplotlib.cbook.deprecation.MatplotlibDeprecationWarning. Please use the MatplotlibDeprecationWarning directly if neccessary.

matplotlib.cbook.Bunch deprecated

The matplotlib.cbook.Bunch class has been deprecated. Instead, use types.SimpleNamespace from the standard library which provides the same functionality.

Deprecation of certain marker styles

Using (n, 3) as marker style to specify a circle marker is deprecated. Use "o" instead.

Using ([(x0, y0), (x1, y1), ...], 0) as marker style to specify a custom marker path is deprecated. Use [(x0, y0), (x1, y1), ...] instead.

Removal of deprecated backends

Deprecated backends have been removed:

  • GTKAgg
  • GTKCairo
  • GTK
  • GDK

Axes3D.get_xlim, get_ylim and get_zlim now return a tuple

They previously returned an array. Returning a tuple is consistent with the behavior for 2D axes.

Modified APIs

The following APIs have been modified:

  • Axes.mouseover_set is now a frozenset, and deprecated. Directly manipulate the artist's .mouseover attribute to change their mouseover status.

Removal of deprecated APIs

The following deprecated API elements have been removed:

  • matplotlib.checkdep_tex, matplotlib.checkdep_xmllint,
  • backend_bases.IdleEvent,
  • cbook.converter, cbook.tostr, cbook.todatetime, cbook.todate, cbook.tofloat, cbook.toint, cbook.unique, cbook.is_string_like, cbook.is_sequence_of_strings, cbook.is_scalar, cbook.soundex, cbook.dict_delall, cbook.get_split_ind, cbook.wrap, cbook.get_recursive_filelist, cbook.pieces, cbook.exception_to_str, cbook.allequal, cbook.alltrue, cbook.onetrue, cbook.allpairs, cbook.finddir, cbook.reverse_dict, cbook.restrict_dict, cbook.issubclass_safe, cbook.recursive_remove, cbook.unmasked_index_ranges, cbook.Null, cbook.RingBuffer, cbook.Sorter, cbook.Xlator,
  • font_manager.weight_as_number, font_manager.ttfdict_to_fnames,
  • pyplot.colors, pyplot.spectral,
  • rcsetup.validate_negative_linestyle, rcsetup.validate_negative_linestyle_legacy,
  • testing.decorators.knownfailureif, testing.decorators.ImageComparisonTest.remove_text,
  • tests.assert_str_equal, tests.test_tinypages.file_same,
  • texmanager.dvipng_hack_alpha,
  • _AxesBase.axesPatch, _AxesBase.set_color_cycle, _AxesBase.get_cursor_props, _AxesBase.set_cursor_props,
  • _ImageBase.iterpnames,
  • FigureCanvasBase.start_event_loop_default;
  • FigureCanvasBase.stop_event_loop_default;
  • Figure.figurePatch,
  • FigureCanvasBase.dynamic_update, FigureCanvasBase.idle_event, FigureCanvasBase.get_linestyle, FigureCanvasBase.set_linestyle,
  • FigureCanvasQTAgg.blitbox,
  • passing non-numbers to EngFormatter.format_eng,
  • passing frac to PolarAxes.set_theta_grids,
  • any mention of idle events,

The following API elements have been removed:

  • backend_cairo.HAS_CAIRO_CFFI,
  • sphinxext.sphinx_version,

font_manager.list_fonts now follows the platform's casefolding semantics

i.e., it behaves case-insensitively on Windows only.

bar/barh no longer accepts left/bottom as first named argument

These arguments were renamed in 2.0 to x/y following the change of the default alignment from edge to center.

Different exception types for undocumented options

  • Passing style='comma' to ticklabel_format() was never supported. It now raises ValueError like all other unsupported styles, rather than NotImplementedError.
  • Passing the undocumented xmin or xmax arguments to set_xlim() would silently override the left and right arguments. set_ylim() and the 3D equivalents (e.g. set_zlim3d()) had a corresponding problem. The _min and _max arguments are now deprecated, and a TypeError will be raised if they would override the earlier limit arguments.

Improved call signature for Axes.margins()

matplotlib.axes.Axes.margins() and mpl_toolkits.mplot3d.Axes3D.margins() no longer accept arbitrary keywords. TypeError will therefore be raised if unknown kwargs are passed; previously they would be silently ignored.

If too many positional arguments are passed, TypeError will be raised instead of ValueError, for consistency with other call-signature violations.

Axes3D.margins now raises TypeError instead of emitting a deprecation warning if only two positional arguments are passed. To supply only x and y margins, use keyword arguments.

lib/mpl_examples removed

The symlink from lib/mpl_examples to ../examples has been removed. This is not installed as an importable package and should not affect end users, however this may require down-stream packagers to adjust. The content is still available top-level examples directory.

Explicit arguments instead of *args, **kwargs

PEP 3102 describes keyword-only arguments, which allow Matplotlib to provide explicit call signatures - where we previously used *args, **kwargs and kwargs.pop, we can now expose named arguments. In some places, unknown kwargs were previously ignored but now raise TypeError because **kwargs has been removed.

  • matplotlib.axes.Axes.stem() no longer accepts unknown keywords, and raises TypeError instead of emitting a deprecation.
  • mpl_toolkits.axes_grid1.axes_divider.SubPlotDivider() raises TypeError instead of Exception when passed unknown kwargs.

Consistent handling of *args in Axes.stem

matplotlib.axex.Axes.stem() now raises TypeError when passed unhandled positional arguments. If two or more arguments are passed (ie X, Y, [linefmt], ...) and Y cannot be cast to an array, an error will be raised instead of treating X as Y and Y as linefmt.

Cleanup decorators and test classes no longer destroy warnings filter on exit

The decorators and classes in matplotlib.testing.decorators no longer destroy the warnings filter on exit. Instead, they restore the warnings filter that existed before the test started using warnings.catch_warnings.

Non-interactive FigureManager classes are now aliases of FigureManagerBase

The FigureManagerPdf, FigureManagerPS, and FigureManagerSVG classes, which were previously empty subclasses of FigureManagerBase (i.e., not adding or overriding any attribute or method), are now direct aliases for FigureManagerBase.

Change to the output of image.thumbnail

When called with preview=False, image.thumbnail previously returned an figure whose canvas class was set according to the output file extension. It now returns a figure whose canvas class is the base FigureCanvasBase (and relies on FigureCanvasBase.print_figure) to handle the canvas switching properly).

As a side effect of this change, image.thumbnail now also supports .ps, .eps, and .svgz output.

Removed proprietary sphinx directives

The matplotlib documentation used the proprietary sphinx directives htmlonly::, and latexonly::. These have been replaced with the standard sphinx directives only:: html and only:: latex. This change will not affect any users. Only downstream package maintainers, who have used the proprietary directives in their docs, will have to switch to the sphinx directives.

FuncAnimation now draws artists according to their zorder when blitting

FuncAnimation now draws artists returned by the user- function according to their zorder when using blitting, instead of using the order in which they are being passed. However, note that only zorder of passed artists will be respected, as they are drawn on top of any existing artists (see #11369).

Contour color autoscaling improvements

Selection of contour levels is now the same for contour and contourf; previously, for contour, levels outside the data range were deleted. (Exception: if no contour levels are found within the data range, the levels attribute is replaced with a list holding only the minimum of the data range.)

When contour is called with levels specified as a target number rather than a list, and the 'extend' kwarg is used, the levels are now chosen such that some data typically will fall in the extended range.

When contour is called with a LogNorm or a LogLocator, it will now select colors using the geometric mean rather than the arithmetic mean of the contour levels.

Streamplot last row and column fixed

A bug was fixed where the last row and column of data in streamplot were being dropped.

Changes to backend loading

Failure to load backend modules (macosx on non-framework builds and gtk3 when running headless) now raises ImportError (instead of RuntimeError and TypeError, respectively).

Third-party backends that integrate with an interactive framework are now encouraged to define the required_interactive_framework global value to one of the following values: "qt5", "qt4", "gtk3", "wx", "tk", or "macosx". This information will be used to determine whether it is possible to switch from a backend to another (specifically, whether they use the same interactive framework).

Changed default AutoDateLocator kwarg interval_multiples to True

The default value of the tick locator for dates, dates.AutoDateLocator kwarg interval_multiples was set to False which leads to not-nice looking automatic ticks in many instances. The much nicer interval_multiples=True is the new default. See below to get the old behavior back:

Axes.get_position now returns actual position if aspect changed

Axes.get_position used to return the original position unless a draw had been triggered or Axes.apply_aspect had been called, even if the kwarg original was set to False. Now Axes.apply_aspect is called so ax.get_position() will return the new modified position. To get the old behaviour use ax.get_position(original=True).

The ticks for colorbar now adjust for the size of the colorbar

Colorbar ticks now adjust for the size of the colorbar if the colorbar is made from a mappable that is not a contour or doesn't have a BoundaryNorm, or boundaries are not specified. If boundaries, etc are specified, the colorbar maintains the original behaviour.

Colorbar for log-scaled hexbin

When using hexbin and plotting with a logarithmic color scale, the colorbar ticks are now correctly log scaled. Previously the tick values were linear scaled log(number of counts).