API Changes in 1.5.0

Code Changes

Reversed matplotlib.cbook.ls_mapper, added ls_mapper_r

Formerly, matplotlib.cbook.ls_mapper was a dictionary with the long-form line-style names ("solid") as keys and the short forms ("-") as values. This long-to-short mapping is now done by ls_mapper_r, and the short-to-long mapping is done by the ls_mapper.

Prevent moving artists between Axes, Property-ify Artist.axes, deprecate Artist.{get,set}_axes

This was done to prevent an Artist that is already associated with an Axes from being moved/added to a different Axes. This was never supported as it causes havoc with the transform stack. The apparent support for this (as it did not raise an exception) was the source of multiple bug reports and questions on SO.

For almost all use-cases, the assignment of the axes to an artist should be taken care of by the axes as part of the Axes.add_* method, hence the deprecation of {get,set}_axes.

Removing the set_axes method will also remove the 'axes' line from the ACCEPTS kwarg tables (assuming that the removal date gets here before that gets overhauled).

Tightened input validation on 'pivot' kwarg to quiver

Tightened validation so that only {'tip', 'tail', 'mid', and 'middle'} (but any capitalization) are valid values for the pivot keyword argument in the Quiver class (and hence axes.Axes.quiver and pyplot.quiver which both fully delegate to Quiver). Previously any input matching 'mid.*' would be interpreted as 'middle', 'tip.*' as 'tip' and any string not matching one of those patterns as 'tail'.

The value of Quiver.pivot is normalized to be in the set {'tip', 'tail', 'middle'} in Quiver.

Reordered Axes.get_children

The artist order returned by axes.Axes.get_children did not match the one used by axes.Axes.draw. They now use the same order, as axes.Axes.draw now calls axes.Axes.get_children.

Changed behaviour of contour plots

The default behaviour of contour() and contourf() when using a masked array is now determined by the new keyword argument corner_mask, or if this is not specified then the new rcParams["contour.corner_mask"] (default: True) instead. The new default behaviour is equivalent to using corner_mask=True; the previous behaviour can be obtained using corner_mask=False or by changing the rcParam. The example https://matplotlib.org/examples/pylab_examples/contour_corner_mask.html demonstrates the difference. Use of the old contouring algorithm, which is obtained with corner_mask='legacy', is now deprecated.

Contour labels may now appear in different places than in earlier versions of Matplotlib.

In addition, the keyword argument nchunk now applies to contour() as well as contourf(), and it subdivides the domain into subdomains of exactly nchunk by nchunk quads, whereas previously it was only roughly nchunk by nchunk quads.

The C/C++ object that performs contour calculations used to be stored in the public attribute QuadContourSet.Cntr, but is now stored in a private attribute and should not be accessed by end users.

Added set_params function to all Locator types

This was a bug fix targeted at making the api for Locators more consistent.

In the old behavior, only locators of type MaxNLocator have set_params() defined, causing its use on any other Locator to raise an AttributeError ( aside: set_params(args) is a function that sets the parameters of a Locator instance to be as specified within args). The fix involves moving set_params() to the Locator class such that all subtypes will have this function defined.

Since each of the Locator subtypes have their own modifiable parameters, a universal set_params() in Locator isn't ideal. Instead, a default no-operation function that raises a warning is implemented in Locator. Subtypes extending Locator will then override with their own implementations. Subtypes that do not have a need for set_params() will fall back onto their parent's implementation, which raises a warning as intended.

In the new behavior, Locator instances will not raise an AttributeError when set_params() is called. For Locators that do not implement set_params(), the default implementation in Locator is used.

Disallow None as x or y value in ax.plot

Do not allow None as a valid input for the x or y args in axes.Axes.plot. This may break some user code, but this was never officially supported (ex documented) and allowing None objects through can lead to confusing exceptions downstream.

To create an empty line use

ln1, = ax.plot([], [], ...)
ln2, = ax.plot([], ...)

In either case to update the data in the Line2D object you must update both the x and y data.

Removed args and kwargs from MicrosecondLocator.__call__

The call signature of __call__() has changed from __call__(self, *args, **kwargs) to __call__(self). This is consistent with the superclass Locator and also all the other Locators derived from this superclass.

No ValueError for the MicrosecondLocator and YearLocator

The MicrosecondLocator and YearLocator objects when called will return an empty list if the axes have no data or the view has no interval. Previously, they raised a ValueError. This is consistent with all the Date Locators.

'OffsetBox.DrawingArea' respects the 'clip' keyword argument

The call signature was OffsetBox.DrawingArea(..., clip=True) but nothing was done with the clip argument. The object did not do any clipping regardless of that parameter. Now the object can and does clip the child Artists if they are set to be clipped.

You can turn off the clipping on a per-child basis using child.set_clip_on(False).

Add salt to clipPath id

Add salt to the hash used to determine the id of the clipPath nodes. This is to avoid conflicts when two svg documents with the same clip path are included in the same document (see https://github.com/ipython/ipython/issues/8133 and https://github.com/matplotlib/matplotlib/issues/4349 ), however this means that the svg output is no longer deterministic if the same figure is saved twice. It is not expected that this will affect any users as the current ids are generated from an md5 hash of properties of the clip path and any user would have a very difficult time anticipating the value of the id.

Changed snap threshold for circle markers to inf

When drawing circle markers above some marker size (previously 6.0) the path used to generate the marker was snapped to pixel centers. However, this ends up distorting the marker away from a circle. By setting the snap threshold to inf snapping is never done on circles.

This change broke several tests, but is an improvement.

Preserve units with Text position

Previously the 'get_position' method on Text would strip away unit information even though the units were still present. There was no inherent need to do this, so it has been changed so that unit data (if present) will be preserved. Essentially a call to 'get_position' will return the exact value from a call to 'set_position'.

If you wish to get the old behaviour, then you can use the new method called 'get_unitless_position'.

New API for custom Axes view changes

Interactive pan and zoom were previously implemented using a Cartesian-specific algorithm that was not necessarily applicable to custom Axes. Three new private methods, matplotlib.axes._base._AxesBase._get_view, matplotlib.axes._base._AxesBase._set_view, and matplotlib.axes._base._AxesBase._set_view_from_bbox, allow for custom Axes classes to override the pan and zoom algorithms. Implementors of custom Axes who override these methods may provide suitable behaviour for both pan and zoom as well as the view navigation buttons on the interactive toolbars.

MathTex visual changes

The spacing commands in mathtext have been changed to more closely match vanilla TeX.

Improved spacing in mathtext

The extra space that appeared after subscripts and superscripts has been removed.

No annotation coordinates wrap

In #2351 for 1.4.0 the behavior of ['axes points', 'axes pixel', 'figure points', 'figure pixel'] as coordinates was change to no longer wrap for negative values. In 1.4.3 this change was reverted for 'axes points' and 'axes pixel' and in addition caused 'axes fraction' to wrap. For 1.5 the behavior has been reverted to as it was in 1.4.0-1.4.2, no wrapping for any type of coordinate.


Deprecated GraphicsContextBase.set_graylevel

The GraphicsContextBase.set_graylevel function has been deprecated in 1.5 and will be removed in 1.6. It has been unused. The GraphicsContextBase.set_foreground could be used instead.

deprecated idle_event

The idle_event was broken or missing in most backends and causes spurious warnings in some cases, and its use in creating animations is now obsolete due to the animations module. Therefore code involving it has been removed from all but the wx backend (where it partially works), and its use is deprecated. The animation module may be used instead to create animations.

color_cycle deprecated

In light of the new property cycling feature, the Axes method set_color_cycle is now deprecated. Calling this method will replace the current property cycle with one that cycles just the given colors.

Similarly, the rc parameter axes.color_cycle is also deprecated in lieu of the new rcParams["axes.prop_cycle"] (default: cycler('color', ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf'])) parameter. Having both parameters in the same rc file is not recommended as the result cannot be predicted. For compatibility, setting axes.color_cycle will replace the cycler in rcParams["axes.prop_cycle"] (default: cycler('color', ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf'])) with a color cycle. Accessing axes.color_cycle will return just the color portion of the property cycle, if it exists.

Timeline for removal has not been set.

Bundled jquery

The version of jquery bundled with the webagg backend has been upgraded from 1.7.1 to 1.11.3. If you are using the version of jquery bundled with webagg you will need to update your html files as such

-    <script src="_static/jquery/js/jquery-1.7.1.min.js"></script>
+    <script src="_static/jquery/js/jquery-1.11.3.min.js"></script>

Code Removed

Removed Image from main namespace

Image was imported from PIL/pillow to test if PIL is available, but there is no reason to keep Image in the namespace once the availability has been determined.

Removed lod from Artist

Removed the method set_lod and all references to the attribute _lod as they are not used anywhere else in the code base. It appears to be a feature stub that was never built out.

Removed Lena images from sample_data

The lena.png and lena.jpg images have been removed from Matplotlib's sample_data directory. The images are also no longer available from matplotlib.cbook.get_sample_data. We suggest using matplotlib.cbook.get_sample_data('grace_hopper.png') or matplotlib.cbook.get_sample_data('grace_hopper.jpg') instead.


Removed handling of loc as a positional argument to Legend

Legend handlers

Remove code to allow legend handlers to be callable. They must now implement a method legend_artist.


Removed method set_scale. This is now handled via a private method which should not be used directly by users. It is called via Axes.set_{x,y}scale which takes care of ensuring the related changes are also made to the Axes object.


Removed functions with ambiguous argument order from finance.py


Removed textcoords and xytext proprieties from Annotation objects.


Both ipython_console_highlighting and ipython_directive have been moved to IPython.

Change your import from matplotlib.sphinxext.ipython_directive to IPython.sphinxext.ipython_directive and from matplotlib.sphinxext.ipython_directive to IPython.sphinxext.ipython_directive


Deprecated in 2005, use set_color

remove 'faceted' as a valid value for shading in tri.tripcolor

Use edgecolor instead. Added validation on shading to only be valid values.

Remove faceted kwarg from scatter

Remove support for the faceted kwarg. This was deprecated in d48b34288e9651ff95c3b8a071ef5ac5cf50bae7 (2008-04-18!) and replaced by edgecolor.

Remove set_colorbar method from ScalarMappable

Remove set_colorbar method, use colorbar attribute directly.


  • remove get_proxy_renderer method from AbstarctPathEffect class

  • remove patch_alpha and offset_xy from SimplePatchShadow

Remove testing.image_util.py

Contained only a no-longer used port of functionality from PIL

Remove mlab.FIFOBuffer

Not used internally and not part of core mission of mpl.

Remove mlab.prepca

Deprecated in 2009.

Remove NavigationToolbar2QTAgg

Added no functionality over the base NavigationToolbar2Qt


Remove the module matplotlib.mpl. Deprecated in 1.3 by PR #1670 and commit 78ce67d161625833cacff23cfe5d74920248c5b2