API Changes in 2.1.0#

Default behavior of log scales changed to mask <= 0 values#

Calling matplotlib.axes.Axes.set_xscale or matplotlib.axes.Axes.set_yscale now uses 'mask' as the default method to handle invalid values (as opposed to 'clip'). This means that any values <= 0 on a log scale will not be shown.

Previously they were clipped to a very small number and shown.

matplotlib.cbook.CallbackRegistry.process() suppresses exceptions by default#

Matplotlib uses instances of CallbackRegistry as a bridge between user input event from the GUI and user callbacks. Previously, any exceptions raised in a user call back would bubble out of the process method, which is typically in the GUI event loop. Most GUI frameworks simple print the traceback to the screen and continue as there is not always a clear method of getting the exception back to the user. However PyQt5 now exits the process when it receives an un-handled python exception in the event loop. Thus, process() now suppresses and prints tracebacks to stderr by default.

What process() does with exceptions is now user configurable via the exception_handler attribute and kwarg. To restore the previous behavior pass None

cb = CallbackRegistry(exception_handler=None)

A function which take and Exception as its only argument may also be passed

def maybe_reraise(exc):
    if isinstance(exc, RuntimeError):
        raise exc

cb = CallbackRegistry(exception_handler=maybe_reraise)

Improved toggling of the axes grids#

The g key binding now switches the states of the x and y grids independently (by cycling through all four on/off combinations).

The new G key binding switches the states of the minor grids.

Both bindings are disabled if only a subset of the grid lines (in either direction) is visible, to avoid making irreversible changes to the figure.

Ticklabels are turned off instead of being invisible#

Internally, the Tick's ~matplotlib.axis.Tick.label1On attribute is now used to hide tick labels instead of setting the visibility on the tick label objects. This improves overall performance and fixes some issues. As a consequence, in case those labels ought to be shown, tick_params() needs to be used, e.g.


Removal of warning on empty legends#

pyplot.legend used to issue a warning when no labeled artist could be found. This warning has been removed.

More accurate legend autopositioning#

Automatic positioning of legends now prefers using the area surrounded by a Line2D rather than placing the legend over the line itself.

Cleanup of stock sample data#

The sample data of stocks has been cleaned up to remove redundancies and increase portability. The AAPL.dat.gz, INTC.dat.gz and aapl.csv files have been removed entirely and will also no longer be available from matplotlib.cbook.get_sample_data. If a CSV file is required, we suggest using the msft.csv that continues to be shipped in the sample data. If a NumPy binary file is acceptable, we suggest using one of the following two new files. The aapl.npy.gz and goog.npy files have been replaced by aapl.npz and goog.npz, wherein the first column's type has changed from datetime.date to numpy.datetime64 for better portability across Python versions. Note that Matplotlib does not fully support numpy.datetime64 as yet.

Updated qhull to 2015.2#

The version of qhull shipped with Matplotlib, which is used for Delaunay triangulation, has been updated from version 2012.1 to 2015.2.

Improved Delaunay triangulations with large offsets#

Delaunay triangulations now deal with large x,y offsets in a better way. This can cause minor changes to any triangulations calculated using Matplotlib, i.e. any use of matplotlib.tri.Triangulation that requests that a Delaunay triangulation is calculated, which includes matplotlib.pyplot.tricontour, matplotlib.pyplot.tricontourf, matplotlib.pyplot.tripcolor, matplotlib.pyplot.triplot, matplotlib.mlab.griddata and mpl_toolkits.mplot3d.axes3d.Axes3D.plot_trisurf.

Use backports.functools_lru_cache instead of functools32#

It's better maintained and more widely used (by pylint, jaraco, etc).

cbook.is_numlike only performs an instance check#

matplotlib.cbook.is_numlike now only checks that its argument is an instance of (numbers.Number, np.Number). In particular, this means that arrays are now not num-like.

Elliptical arcs now drawn between correct angles#

The matplotlib.patches.Arc patch is now correctly drawn between the given angles.

Previously a circular arc was drawn and then stretched into an ellipse, so the resulting arc did not lie between theta1 and theta2.

-d$backend no longer sets the backend#

It is no longer possible to set the backend by passing -d$backend at the command line. Use the MPLBACKEND environment variable instead.

Path.intersects_bbox always treats the bounding box as filled#

Previously, when Path.intersects_bbox was called with filled set to False, it would treat both the path and the bounding box as unfilled. This behavior was not well documented and it is usually not the desired behavior, since bounding boxes are used to represent more complex shapes located inside the bounding box. This behavior has now been changed: when filled is False, the path will be treated as unfilled, but the bounding box is still treated as filled. The old behavior was arguably an implementation bug.

When Path.intersects_bbox is called with filled set to True (the default value), there is no change in behavior. For those rare cases where Path.intersects_bbox was called with filled set to False and where the old behavior is actually desired, the suggested workaround is to call Path.intersects_path with a rectangle as the path:

from matplotlib.path import Path
from matplotlib.transforms import Bbox, BboxTransformTo
rect = Path.unit_rectangle().transformed(BboxTransformTo(bbox))
result = path.intersects_path(rect, filled=False)

WX no longer calls generates IdleEvent events or calls idle_event#

Removed unused private method _onIdle from FigureCanvasWx.

The IdleEvent class and FigureCanvasBase.idle_event method will be removed in 2.2

Correct scaling of magnitude_spectrum()#

The functions matplotlib.mlab.magnitude_spectrum() and matplotlib.pyplot.magnitude_spectrum() implicitly assumed the sum of windowing function values to be one. In Matplotlib and Numpy the standard windowing functions are scaled to have maximum value of one, which usually results in a sum of the order of n/2 for a n-point signal. Thus the amplitude scaling magnitude_spectrum() was off by that amount when using standard windowing functions (Bug 8417 ). Now the behavior is consistent with matplotlib.pyplot.psd() and scipy.signal.welch(). The following example demonstrates the new and old scaling:

import matplotlib.pyplot as plt
import numpy as np

tau, n = 10, 1024  # 10 second signal with 1024 points
T = tau/n  # sampling interval
t = np.arange(n)*T

a = 4  # amplitude
x = a*np.sin(40*np.pi*t)  # 20 Hz sine with amplitude a

# New correct behavior: Amplitude at 20 Hz is a/2
plt.magnitude_spectrum(x, Fs=1/T, sides='onesided', scale='linear')

# Original behavior: Amplitude at 20 Hz is (a/2)*(n/2) for a Hanning window
w = np.hanning(n)  # default window is a Hanning window
plt.magnitude_spectrum(x*np.sum(w), Fs=1/T, sides='onesided', scale='linear')

Change to signatures of bar() & barh()#

For 2.0 the default value of *align* changed to 'center'. However this caused the signature of bar() and barh() to be misleading as the first parameters were still left and bottom respectively:

bar(left, height, *, align='center', **kwargs)
barh(bottom, width, *, align='center', **kwargs)

despite behaving as the center in both cases. The methods now take *args, **kwargs as input and are documented to have the primary signatures of:

bar(x, height, *, align='center', **kwargs)
barh(y, width, *, align='center', **kwargs)

Passing left and bottom as keyword arguments to bar() and barh() respectively will warn. Support will be removed in Matplotlib 3.0.

Font cache as json#

The font cache is now saved as json, rather than a pickle.

Invalid (Non-finite) Axis Limit Error#

When using set_xlim() and set_ylim(), passing non-finite values now results in a ValueError. The previous behavior resulted in the limits being erroneously reset to (-0.001, 0.001).

scatter and Collection offsets are no longer implicitly flattened#

Collection (and thus both 2D scatter and 3D scatter) no longer implicitly flattens its offsets. As a consequence, scatter's x and y arguments can no longer be 2+-dimensional arrays.


GraphicsContextBase's linestyle property.#

The GraphicsContextBase.get_linestyle and GraphicsContextBase.set_linestyle methods, which had no effect, have been deprecated. All of the backends Matplotlib ships use GraphicsContextBase.get_dashes and GraphicsContextBase.set_dashes which are more general. Third-party backends should also migrate to the *_dashes methods.


matplotlib.testing.noseclasses is deprecated and will be removed in 2.3

EngFormatter num arg as string#

Passing a string as num argument when calling an instance of matplotlib.ticker.EngFormatter is deprecated and will be removed in 2.3.

mpl_toolkits.axes_grid module#

All functionally from mpl_toolkits.axes_grid can be found in either mpl_toolkits.axes_grid1 or mpl_toolkits.axisartist. Axes classes from mpl_toolkits.axes_grid based on Axis from mpl_toolkits.axisartist can be found in mpl_toolkits.axisartist.

Axes collision in Figure.add_axes#

Adding an axes instance to a figure by using the same arguments as for a previous axes instance currently reuses the earlier instance. This behavior has been deprecated in Matplotlib 2.1. In a future version, a new instance will always be created and returned. Meanwhile, in such a situation, a deprecation warning is raised by matplotlib.figure.AxesStack.

This warning can be suppressed, and the future behavior ensured, by passing a unique label to each axes instance. See the docstring of add_axes() for more information.

Additional details on the rationale behind this deprecation can be found in #7377 and #9024.

Former validators for contour.negative_linestyle#

The former public validation functions validate_negative_linestyle and validate_negative_linestyle_legacy will be deprecated in 2.1 and may be removed in 2.3. There are no public functions to replace them.


Many unused or near-unused matplotlib.cbook functions and classes have been deprecated: converter, tostr, todatetime, todate, tofloat, toint, unique, is_string_like, is_sequence_of_strings, is_scalar, Sorter, Xlator, soundex, Null, dict_delall, RingBuffer, get_split_ind, wrap, get_recursive_filelist, pieces, exception_to_str, allequal, alltrue, onetrue, allpairs, finddir, reverse_dict, restrict_dict, issubclass_safe, recursive_remove, unmasked_index_ranges.

Code Removal#


Moved to qt_compat.py. Renamed because it now handles Qt5 as well.

Previously Deprecated methods#

The GraphicsContextBase.set_graylevel, FigureCanvasBase.onHilite and mpl_toolkits.axes_grid1.mpl_axes.Axes.toggle_axisline methods have been removed.

The ArtistInspector.findobj method, which was never working due to the lack of a get_children method, has been removed.

The deprecated point_in_path, get_path_extents, point_in_path_collection, path_intersects_path, convert_path_to_polygons, cleanup_path and clip_path_to_rect functions in the matplotlib.path module have been removed. Their functionality remains exposed as methods on the Path class.

The deprecated Artist.get_axes and Artist.set_axes methods have been removed

The matplotlib.backends.backend_ps.seq_allequal function has been removed. Use np.array_equal instead.

The deprecated matplotlib.rcsetup.validate_maskedarray, matplotlib.rcsetup.deprecate_savefig_extension and matplotlib.rcsetup.validate_tkpythoninspect functions, and associated savefig.extension and tk.pythoninspect rcparams entries have been removed.

The keyword argument resolution of matplotlib.projections.polar.PolarAxes has been removed. It has deprecation with no effect from version 0.98.x.


Support for setting an Axes's aspect to "normal" has been removed, in favor of the synonym "auto".

shading kwarg to pcolor#

The shading kwarg to pcolor has been removed. Set edgecolors appropriately instead.

Functions removed from the lines module#

The matplotlib.lines module no longer imports the pts_to_prestep, pts_to_midstep and pts_to_poststep functions from matplotlib.cbook.

PDF backend functions#

The methods embedTeXFont and tex_font_mapping of matplotlib.backends.backend_pdf.PdfFile have been removed. It is unlikely that external users would have called these methods, which are related to the font system internal to the PDF backend.


Remove the delaunay triangulation code which is now handled by Qhull via matplotlib.tri.