Skip to content
D3 Renderings of Matplotlib Graphics
Branch: master
Clone or download
Latest commit a311c66 Jul 23, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin script to write version.js Mar 28, 2014
doc Fix sphinx docs notebook conversion Nov 4, 2016
examples Fix: There Nov 16, 2017
icons add icons to repository Mar 17, 2014
mpld3 Added serializer fix from #434. Mar 12, 2018
mplexporter @ a6bb9fe Update submodule hash Nov 2, 2016
notebooks Add missing NumPy import Jul 6, 2015
src update version to 0.3.1.dev1 Nov 30, 2016
test Fix for NaN/Inf line tests Sep 14, 2016
.gitignore TST: rework test plots for cleaner testing Apr 14, 2014
.gitmodules revert to mpld3 mplexporter May 26, 2016
.travis.yml Test with matplotlib 1.5 on Travis Nov 2, 2016 DOC: update website theme Apr 21, 2014 Use CamelCase spelling for JavaScript in docs Apr 26, 2014
LICENSE Initial commit Dec 18, 2013 BUG: fix test script in manifest Apr 21, 2014
Makefile makefile: fix version script Apr 29, 2014 Updated maintenance note Jul 23, 2018 update RELEASING instructions with website build Jul 23, 2015 added check for existing submodule source directory May 14, 2014 Remove unused imports Oct 5, 2016
package.json Use d3 v3.5.12 Sep 2, 2016
setup.cfg add setup.cfg Feb 11, 2014 DOC: add python 3.4 to Apr 15, 2014 use ast rather than re to get version Mar 28, 2014 Fix JSON not serializable Jan 14, 2016

mpld3: A D3 Viewer for Matplotlib

Note: mpld3 is in the process of switching maintainers: feature requests & bug reports are likely to be delayed. If you are interested in contributing to this project, please contact one of the repository owners.

This is an interactive D3js-based viewer which brings matplotlib graphics to the browser. Please visit for documentation and examples.

You may also see the blog post, or the IPython notebook examples available in the notebooks directory of this repository.

version status downloads build status


mpld3 provides a custom stand-alone javascript library built on D3, which parses JSON representations of plots. The mpld3 python module provides a set of routines which parses matplotlib plots (using the mplexporter framework) and outputs the JSON description readable by mpld3.js.


mpld3 is compatible with python 2.6-2.7 and 3.3-3.4. It requires matplotlib version 1.3 and jinja2 version 2.7+.

Optionally, mpld3 can be used with IPython notebook, and requires IPython version 1.x or (preferably) version 2.0+.

This package is based on the mplexporter framework for crawling and exporting matplotlib images. mplexporter is bundled with the source distribution via git submodule.

Within the git source directory, you can download the mplexporter dependency and copy it into the mpld3 source directory using the following command:

[~]$ python submodule

The submodule command is not necessary if you are installing from a distribution rather than from the git source.

Once the submodule command has been run, you can build the package locally using

[~]$ python build

or install the package to the standard Python path using:

[~]$ python install

Or, to install to another location, use

[~]$ python install --prefix=/path/to/location/

Then make sure your PYTHONPATH environment variable points to this location.

Trying it out

The package is pure python, and very light-weight. You can take a look at the notebooks in the examples directory, or run, which will create a set of plots and launch a browser window showing interactive views of these plots.

For a more comprehensive set of examples, see the IPython notebook examples available in the notebooks directory.

Test Plots

To explore the comparison between D3 renderings and matplotlib renderings for various plot types, run the script This will generate an HTML page with the D3 renderings beside corresponding matplotlib renderings.


Many of the core features of matplotlib are already supported. And additionally there is some extra interactivity provided via the plugin framework. The following is a non-exhausive list of features that are yet to be supported:

  • tick specification & formatting
  • some legend features
  • blended transforms, such as those required by axvlines and axhlines
  • twin axes (i.e. multiple scales on one plot) tied together

If any of these look like something you'd like to tackle, feel free to submit a pull request!

You can’t perform that action at this time.