You are reading an old version of the documentation (v1.2.1). For the latest version see

Table Of Contents

Previous topic


Next topic

Github stats

This Page

What’s new in matplotlib

This page just covers the highlights – for the full story, see the CHANGELOG

For a list of all of the issues and pull requests since the last revision, see the github-stats.


Matplotlib version 1.1 is the last major release compatible with Python versions 2.4 to 2.7. matplotlib 1.2 and later require versions 2.6, 2.7, and 3.1 and higher.

new in matplotlib-1.2

Python 3.x support

Matplotlib 1.2 is the first version to support Python 3.x, specifically Python 3.1 and 3.2. To make this happen in a reasonable way, we also had to drop support for Python versions earlier than 2.6.

This work was done by Michael Droettboom, the Cape Town Python Users’ Group, many others and supported financially in part by the SAGE project.

The following GUI backends work under Python 3.x: Gtk3Cairo, Qt4Agg, TkAgg and MacOSX. The other GUI backends do not yet have adequate bindings for Python 3.x, but continue to work on Python 2.6 and 2.7, particularly the Qt and QtAgg backends (which have been deprecated). The non-GUI backends, such as PDF, PS and SVG, work on both Python 2.x and 3.x.

Features that depend on the Python Imaging Library, such as JPEG handling, do not work, since the version of PIL for Python 3.x is not sufficiently mature.

PGF/TikZ backend

Peter Würtz wrote a backend that allows matplotlib to export figures as drawing commands for LaTeX. These can be processed by PdfLaTeX, XeLaTeX or LuaLaTeX using the PGF/TikZ package. Usage examples and documentation are found in Typesetting With XeLaTeX/LuaLaTeX.


Locator interface

Philip Elson exposed the intelligence behind the tick Locator classes with a simple interface. For instance, to get no more than 5 sensible steps which span the values 10 and 19.5:

>>> import matplotlib.ticker as mticker
>>> locator = mticker.MaxNLocator(nbins=5)
>>> print(locator.tick_values(10, 19.5))
[ 10.  12.  14.  16.  18.  20.]

Tri-Surface Plots

Damon McDougall added a new plotting method for the mplot3d toolkit called plot_trisurf().

(Source code, png, hires.png, pdf)


Control the lengths of colorbar extensions

Andrew Dawson added a new keyword argument extendfrac to colorbar() to control the length of minimum and maximum colorbar extensions.

(Source code, png, hires.png, pdf)


Figures are picklable

Philip Elson added an experimental feature to make figures picklable for quick and easy short-term storage of plots. Pickle files are not designed for long term storage, are unsupported when restoring a pickle saved in another matplotlib version and are insecure when restoring a pickle from an untrusted source. Having said this, they are useful for short term storage for later modification inside matplotlib.

Set default bounding box in matplotlibrc

Two new defaults are available in the matplotlibrc configuration file: savefig.bbox, which can be set to ‘standard’ or ‘tight’, and savefig.pad_inches, which controls the bounding box padding.

New Boxplot Functionality

Users can now incorporate their own methods for computing the median and its confidence intervals into the boxplot() method. For every column of data passed to boxplot, the user can specify an accompanying median and confidence interval.

(Source code, png, hires.png, pdf)


New RC parameter functionality

Matthew Emmett added a function and a context manager to help manage RC parameters: rc_file() and rc_context. To load RC parameters from a file:

>>> mpl.rc_file('mpl.rc')

To temporarily use RC parameters:

>>> with mpl.rc_context(fname='mpl.rc', rc={'text.usetex': True}):
>>>     ...


Tom Flannaghan and Tony Yu have added a new streamplot() function to plot the streamlines of a vector field. This has been a long-requested feature and complements the existing quiver() function for plotting vector fields. In addition to simply plotting the streamlines of the vector field, streamplot() allows users to map the colors and/or line widths of the streamlines to a separate parameter, such as the speed or local intensity of the vector field.

(Source code)

New hist functionality

Nic Eggert added a new stacked kwarg to hist() that allows creation of stacked histograms using any of the histogram types. Previously, this functionality was only available by using the barstacked histogram type. Now, when stacked=True is passed to the function, any of the histogram types can be stacked. The barstacked histogram type retains its previous functionality for backwards compatibility.

Updated shipped dependencies

The following dependencies that ship with matplotlib and are optionally installed alongside it have been updated:

  • pytz 2012d
  • dateutil 1.5 on Python 2.x, and 2.1 on Python 3.x

Face-centred colors in tripcolor plots

Ian Thomas extended tripcolor() to allow one color value to be specified for each triangular face rather than for each point in a triangulation.

(Source code)

Hatching patterns in filled contour plots, with legends

Phil Elson added support for hatching to contourf(), together with the ability to use a legend to identify contoured ranges.

(Source code)

Known issues in the matplotlib-1.2 release

  • When using the Qt4Agg backend with IPython 0.11 or later, the save dialog will not display. This should be fixed in a future version of IPython.

new in matplotlib-1.1

Sankey Diagrams

Kevin Davies has extended Yannick Copin’s original Sankey example into a module (sankey) and provided new examples (api example code:, api example code:, api example code:

(Source code, png, hires.png, pdf)



Ryan May has written a backend-independent framework for creating animated figures. The animation module is intended to replace the backend-specific examples formerly in the Matplotlib Examples listings. Examples using the new framework are in animation Examples; see the entrancing double pendulum which uses to create the movie below.

This should be considered as a beta release of the framework; please try it and provide feedback.

Tight Layout

A frequent issue raised by users of matplotlib is the lack of a layout engine to nicely space out elements of the plots. While matplotlib still adheres to the philosphy of giving users complete control over the placement of plot elements, Jae-Joon Lee created the tight_layout module and introduced a new command tight_layout() to address the most common layout issues.

(Source code, png, hires.png, pdf)


(png, hires.png, pdf)


The usage of this functionality can be as simple as


and it will adjust the spacing between subplots so that the axis labels do not overlap with neighboring subplots. A Tight Layout guide has been created to show how to use this new tool.

PyQT4, PySide, and IPython

Gerald Storer made the Qt4 backend compatible with PySide as well as PyQT4. At present, however, PySide does not support the PyOS_InputHook mechanism for handling gui events while waiting for text input, so it cannot be used with the new version 0.11 of IPython. Until this feature appears in PySide, IPython users should use the PyQT4 wrapper for QT4, which remains the matplotlib default.

An rcParam entry, “backend.qt4”, has been added to allow users to select PyQt4, PyQt4v2, or PySide. The latter two use the Version 2 Qt API. In most cases, users can ignore this rcParam variable; it is available to aid in testing, and to provide control for users who are embedding matplotlib in a PyQt4 or PySide app.


Jae-Joon Lee has improved plot legends. First, legends for complex plots such as stem() plots will now display correctly. Second, the ‘best’ placement of a legend has been improved in the presence of NANs.

See Legend of Complex Plots for more detailed explanation and examples.

(Source code, png, hires.png, pdf)



In continuing the efforts to make 3D plotting in matplotlib just as easy as 2D plotting, Ben Root has made several improvements to the mplot3d module.

  • Axes3D has been improved to bring the class towards feature-parity with regular Axes objects
  • Documentation for mplot3d was significantly expanded
  • Axis labels and orientation improved
  • Most 3D plotting functions now support empty inputs
  • Ticker offset display added:

(Source code, png, hires.png, pdf)

  • contourf() gains zdir and offset kwargs. You can now do this:

(Source code, png, hires.png, pdf)


Numerix support removed

After more than two years of deprecation warnings, Numerix support has now been completely removed from matplotlib.


The list of available markers for plot() and scatter() has now been merged. While they were mostly similar, some markers existed for one function, but not the other. This merge did result in a conflict for the ‘d’ diamond marker. Now, ‘d’ will be interpreted to always mean “thin” diamond while ‘D’ will mean “regular” diamond.

Thanks to Michael Droettboom for this effort.

Other improvements

  • Unit support for polar axes and arrow()
  • PolarAxes gains getters and setters for “theta_direction”, and “theta_offset” to allow for theta to go in either the clock-wise or counter-clockwise direction and to specify where zero degrees should be placed. set_theta_zero_location() is an added convenience function.
  • Fixed error in argument handling for tri-functions such as tripcolor()
  • axes.labelweight parameter added to rcParams.
  • For imshow(), interpolation=’nearest’ will now always perform an interpolation. A “none” option has been added to indicate no interpolation at all.
  • An error in the Hammer projection has been fixed.
  • clabel for contour() now accepts a callable. Thanks to Daniel Hyams for the original patch.
  • Jae-Joon Lee added the HBox and VBox classes.
  • Christoph Gohlke reduced memory usage in imshow().
  • scatter() now accepts empty inputs.
  • The behavior for ‘symlog’ scale has been fixed, but this may result in some minor changes to existing plots. This work was refined by ssyr.
  • Peter Butterworth added named figure support to figure().
  • Michiel de Hoon has modified the MacOSX backend to make its interactive behavior consistent with the other backends.
  • Pim Schellart added a new colormap called “cubehelix”. Sameer Grover also added a colormap called “coolwarm”. See it and all other colormaps here.
  • Many bug fixes and documentation improvements.

new in matplotlib-1.0

HTML5/Canvas backend

Simon Ratcliffe and Ludwig Schwardt have released an HTML5/Canvas backend for matplotlib. The backend is almost feature complete, and they have done a lot of work comparing their html5 rendered images with our core renderer Agg. The backend features client/server interactive navigation of matplotlib figures in an html5 compliant browser.

Sophisticated subplot grid layout

Jae-Joon Lee has written gridspec, a new module for doing complex subplot layouts, featuring row and column spans and more. See Customizing Location of Subplot Using GridSpec for a tutorial overview.

(Source code, png, hires.png, pdf)


Easy pythonic subplots

Fernando Perez got tired of all the boilerplate code needed to create a figure and multiple subplots when using the matplotlib API, and wrote a subplots() helper function. Basic usage allows you to create the figure and an array of subplots with numpy indexing (starts with 0). Eg:

fig, axarr = plt.subplots(2, 2)
axarr[0,0].plot([1,2,3])   # upper, left

See pylab_examples example code: for several code examples.

Contour fixes and and triplot

Ian Thomas has fixed a long-standing bug that has vexed our most talented developers for years. contourf() now handles interior masked regions, and the boundaries of line and filled contours coincide.

Additionally, he has contributed a new module tri and helper function triplot() for creating and plotting unstructured triangular grids.

(Source code)

multiple calls to show supported

A long standing request is to support multiple calls to show(). This has been difficult because it is hard to get consistent behavior across operating systems, user interface toolkits and versions. Eric Firing has done a lot of work on rationalizing show across backends, with the desired behavior to make show raise all newly created figures and block execution until they are closed. Repeated calls to show should raise newly created figures since the last call. Eric has done a lot of testing on the user interface toolkits and versions and platforms he has access to, but it is not possible to test them all, so please report problems to the mailing list and bug tracker.

mplot3d graphs can be embedded in arbitrary axes

You can now place an mplot3d graph into an arbitrary axes location, supporting mixing of 2D and 3D graphs in the same figure, and/or multiple 3D graphs in a single figure, using the “projection” keyword argument to add_axes or add_subplot. Thanks Ben Root.

(Source code, png, hires.png, pdf)



Eric Firing wrote tick_params, a convenience method for changing the appearance of ticks and tick labels. See pyplot function tick_params() and associated Axes method tick_params().

Lots of performance and feature enhancements

  • Faster magnification of large images, and the ability to zoom in to a single pixel
  • Local installs of documentation work better
  • Improved “widgets” – mouse grabbing is supported
  • More accurate snapping of lines to pixel boundaries
  • More consistent handling of color, particularly the alpha channel, throughout the API

Much improved software carpentry

The matplotlib trunk is probably in as good a shape as it has ever been, thanks to improved software carpentry. We now have a buildbot which runs a suite of nose regression tests on every svn commit, auto-generating a set of images and comparing them against a set of known-goods, sending emails to developers on failures with a pixel-by-pixel image comparison. Releases and release bugfixes happen in branches, allowing active new feature development to happen in the trunk while keeping the release branches stable. Thanks to Andrew Straw, Michael Droettboom and other matplotlib developers for the heavy lifting.

Bugfix marathon

Eric Firing went on a bug fixing and closing marathon, closing over 100 bugs on the bug tracker with help from Jae-Joon Lee, Michael Droettboom, Christoph Gohlke and Michiel de Hoon.

new in matplotlib-0.99

New documentation

Jae-Joon Lee has written two new guides Legend guide and Annotating Axes. Michael Sarahan has written Image tutorial. John Hunter has written two new tutorials on working with paths and transformations: Path Tutorial and Transformations Tutorial.


Reinier Heeres has ported John Porter’s mplot3d over to the new matplotlib transformations framework, and it is now available as a toolkit mpl_toolkits.mplot3d (which now comes standard with all mpl installs). See mplot3d Examples and mplot3d tutorial

(Source code, png, hires.png, pdf)


axes grid toolkit

Jae-Joon Lee has added a new toolkit to ease displaying multiple images in matplotlib, as well as some support for curvilinear grids to support the world coordinate system. The toolkit is included standard with all new mpl installs. See axes_grid Examples and The Matplotlib AxesGrid Toolkit User’s Guide.

(Source code, png, hires.png, pdf)


Axis spine placement

Andrew Straw has added the ability to place “axis spines” – the lines that denote the data limits – in various arbitrary locations. No longer are your axis lines constrained to be a simple rectangle around the figure – you can turn on or off left, bottom, right and top, as well as “detach” the spine to offset it away from the data. See pylab_examples example code: and matplotlib.spines.Spine.

(Source code, png, hires.png, pdf)


new in 0.98.4

It’s been four months since the last matplotlib release, and there are a lot of new features and bug-fixes.

Thanks to Charlie Moad for testing and preparing the source release, including binaries for OS X and Windows for python 2.4 and 2.5 (2.6 and 3.0 will not be available until numpy is available on those releases). Thanks to the many developers who contributed to this release, with contributions from Jae-Joon Lee, Michael Droettboom, Ryan May, Eric Firing, Manuel Metz, Jouni K. Seppänen, Jeff Whitaker, Darren Dale, David Kaplan, Michiel de Hoon and many others who submitted patches

Legend enhancements

Jae-Joon has rewritten the legend class, and added support for multiple columns and rows, as well as fancy box drawing. See legend() and matplotlib.legend.Legend.

(Source code, png, hires.png, pdf)


Fancy annotations and arrows

Jae-Joon has added lot’s of support to annotations for drawing fancy boxes and connectors in annotations. See annotate() and BoxStyle, ArrowStyle, and ConnectionStyle.

(Source code, png, hires.png, pdf)


Native OS X backend

Michiel de Hoon has provided a native Mac OSX backend that is almost completely implemented in C. The backend can therefore use Quartz directly and, depending on the application, can be orders of magnitude faster than the existing backends. In addition, no third-party libraries are needed other than Python and NumPy. The backend is interactive from the usual terminal application on Mac using regular Python. It hasn’t been tested with ipython yet, but in principle it should to work there as well. Set ‘backend : macosx’ in your matplotlibrc file, or run your script with:

> python -dmacosx

psd amplitude scaling

Ryan May did a lot of work to rationalize the amplitude scaling of psd() and friends. See pylab_examples example code: and pylab_examples example code: The changes should increase MATLAB compatabililty and increase scaling options.

Fill between

Added a fill_between() function to make it easier to do shaded region plots in the presence of masked data. You can pass an x array and a ylower and yupper array to fill betweem, and an optional where argument which is a logical mask where you want to do the filling.

(Source code, png, hires.png, pdf)


Lots more

Here are the 0.98.4 notes from the CHANGELOG:

Added mdehoon's native macosx backend from sf patch 2179017 - JDH

Removed the prints in the set_*style commands.  Return the list of
pprinted strings instead - JDH

Some of the changes Michael made to improve the output of the
property tables in the rest docs broke of made difficult to use
some of the interactive doc helpers, eg setp and getp.  Having all
the rest markup in the ipython shell also confused the docstrings.
I added a new rc param docstring.harcopy, to format the docstrings
differently for hardcopy and other use.  Ther ArtistInspector
could use a little refactoring now since there is duplication of
effort between the rest out put and the non-rest output - JDH

Updated spectral methods (psd, csd, etc.) to scale one-sided
densities by a factor of 2 and, optionally, scale all densities by
the sampling frequency.  This gives better MATLAB
compatibility. -RM

Fixed alignment of ticks in colorbars. -MGD

drop the deprecated "new" keyword of np.histogram() for numpy 1.2
or later.  -JJL

Fixed a bug in svg backend that new_figure_manager() ignores
keywords arguments such as figsize, etc. -JJL

Fixed a bug that the handlelength of the new legend class set too
short when numpoints=1 -JJL

Added support for data with units (e.g. dates) to
Axes.fill_between. -RM

Added fancybox keyword to legend. Also applied some changes for
better look, including baseline adjustment of the multiline texts
so that it is center aligned. -JJL

The transmuter classes in the are reorganized as
subclasses of the Style classes. A few more box and arrow styles
are added. -JJL

Fixed a bug in the new legend class that didn't allowed a tuple of
coordinate vlaues as loc. -JJL

Improve checks for external dependencies, using subprocess
(instead of deprecated popen*) and distutils (for version
checking) - DSD

Reimplementaion of the legend which supports baseline alignement,
multi-column, and expand mode. - JJL

Fixed histogram autoscaling bug when bins or range are given
explicitly (fixes Debian bug 503148) - MM

Added rcParam axes.unicode_minus which allows plain hypen for
minus when False - JDH

Added scatterpoints support in Legend. patch by Erik Tollerud -

Fix crash in log ticking. - MGD

Added static helper method BrokenHBarCollection.span_where and
Axes/pyplot method fill_between.  See
examples/pylab/ - JDH

Add x_isdata and y_isdata attributes to Artist instances, and use
them to determine whether either or both coordinates are used when
updating dataLim.  This is used to fix autoscaling problems that
had been triggered by axhline, axhspan, axvline, axvspan. - EF

Update the psd(), csd(), cohere(), and specgram() methods of Axes
and the csd() cohere(), and specgram() functions in mlab to be in
sync with the changes to psd().  In fact, under the hood, these
all call the same core to do computations. - RM

Add 'pad_to' and 'sides' parameters to mlab.psd() to allow
controlling of zero padding and returning of negative frequency
components, respecitively.  These are added in a way that does not
change the API. - RM

Fix handling of c kwarg by scatter; generalize is_string_like to
accept numpy and string array scalars. - RM and EF

Fix a possible EINTR problem in dviread, which might help when
saving pdf files from the qt backend. - JKS

Fix bug with zoom to rectangle and twin axes - MGD

Added Jae Joon's fancy arrow, box and annotation enhancements --
see examples/pylab_examples/

Autoscaling is now supported with shared axes - EF

Fixed exception in dviread that happened with Minion - JKS

set_xlim, ylim now return a copy of the viewlim array to avoid
modify inplace surprises

Added image thumbnail generating function
matplotlib.image.thumbnail.  See examples/misc/

Applied scatleg patch based on ideas and work by Erik Tollerud and
Jae-Joon Lee. - MM

Fixed bug in pdf backend: if you pass a file object for output
instead of a filename, e.g. in a wep app, we now flush the object
at the end. - JKS

Add path simplification support to paths with gaps. - EF

Fix problem with AFM files that don't specify the font's full name
or family name. - JKS

Added 'scilimits' kwarg to Axes.ticklabel_format() method, for
easy access to the set_powerlimits method of the major
ScalarFormatter. - EF

Experimental new kwarg borderpad to replace pad in legend, based
on suggestion by Jae-Joon Lee.  - EF

Allow spy to ignore zero values in sparse arrays, based on patch
by Tony Yu.  Also fixed plot to handle empty data arrays, and
fixed handling of markers in figlegend. - EF

Introduce drawstyles for lines. Transparently split linestyles
like 'steps--' into drawstyle 'steps' and linestyle '--'.  Legends
always use drawstyle 'default'. - MM

Fixed quiver and quiverkey bugs (failure to scale properly when
resizing) and added additional methods for determining the arrow
angles - EF

Fix polar interpolation to handle negative values of theta - MGD

Reorganized cbook and mlab methods related to numerical
calculations that have little to do with the goals of those two
modules into a separate module Also, added
ability to select points and stop point selection with keyboard in
ginput and manual contour labeling code.  Finally, fixed contour
labeling bug. - DMK

Fix backtick in Postscript output. - MGD

[ 2089958 ] Path simplification for vector output backends
Leverage the simplification code exposed through path_to_polygons
to simplify certain well-behaved paths in the vector backends
(PDF, PS and SVG).  "path.simplify" must be set to True in
matplotlibrc for this to work.  - MGD

Add "filled" kwarg to Path.intersects_path and
Path.intersects_bbox. - MGD

Changed full arrows slightly to avoid an xpdf rendering problem
reported by Friedrich Hagedorn. - JKS

Fix conversion of quadratic to cubic Bezier curves in PDF and PS
backends. Patch by Jae-Joon Lee. - JKS

Added 5-point star marker to plot command q- EF

Fix hatching in PS backend - MGD

Fix log with base 2 - MGD

Added support for bilinear interpolation in
NonUniformImage; patch by Gregory Lielens. - EF

Added support for multiple histograms with data of
different length - MM

Fix step plots with log scale - MGD

Fix masked arrays with markers in non-Agg backends - MGD

Fix clip_on kwarg so it actually works correctly - MGD

Fix locale problems in SVG backend - MGD

fix quiver so masked values are not plotted - JSW

improve interactive pan/zoom in qt4 backend on windows - DSD

Fix more bugs in NaN/inf handling.  In particular, path
simplification (which does not handle NaNs or infs) will be turned
off automatically when infs or NaNs are present.  Also masked
arrays are now converted to arrays with NaNs for consistent
handling of masks and NaNs - MGD and EF