Previous topic

API Changes

Next topic

afm (Adobe Font Metrics interface)

This Page

The top level matplotlib module

This is an object-oriented plotting library.

A procedural interface is provided by the companion pyplot module, which may be imported directly, e.g.:

from matplotlib.pyplot import *

To include numpy functions too, use:

from pylab import *

or using ipython:

ipython -pylab

For the most part, direct use of the object-oriented library is encouraged when programming; pyplot is primarily for working interactively. The exceptions are the pyplot commands figure(), subplot(), subplots(), show(), and savefig(), which can greatly simplify scripting.

Modules include:

defines the Axes class. Most pylab commands are wrappers for Axes methods. The axes module is the highest level of OO access to the library.
defines the Figure class.
defines the Artist base class for all classes that draw things.
defines the Line2D class for drawing lines and markers
defines classes for drawing polygons
defines the Text, TextWithDash, and Annotate classes
defines the AxesImage and FigureImage classes
classes for efficient drawing of groups of lines or polygons
classes for interpreting color specifications and for making colormaps
colormaps and the ScalarMappable mixin class for providing color mapping functionality to other classes
classes for calculating tick mark locations and for formatting tick labels
a subpackage with modules for various gui libraries and output formats

The base matplotlib namespace includes:

a global dictionary of default configuration settings. It is initialized by code which may be overridded by a matplotlibrc file.
a function for setting groups of rcParams values
a function for setting the matplotlib backend. If used, this function must be called immediately after importing matplotlib for the first time. In particular, it must be called before importing pylab (if pylab is imported).

matplotlib was initially written by John D. Hunter (1968-2012) and is now developed and maintained by a host of others.

Occasionally the internal documentation (python docstrings) will refer to MATLAB®, a registered trademark of The MathWorks, Inc.

matplotlib.rc(group, **kwargs)

Set the current rc params. Group is the grouping for the rc, e.g., for lines.linewidth the group is lines, for axes.facecolor, the group is axes, and so on. Group may also be a list or tuple of group names, e.g., (xtick, ytick). kwargs is a dictionary attribute name/value pairs, eg:

rc('lines', linewidth=2, color='r')

sets the current rc params and is equivalent to:

rcParams['lines.linewidth'] = 2
rcParams['lines.color'] = 'r'

The following aliases are available to save typing for interactive users:

Alias Property
‘lw’ ‘linewidth’
‘ls’ ‘linestyle’
‘c’ ‘color’
‘fc’ ‘facecolor’
‘ec’ ‘edgecolor’
‘mew’ ‘markeredgewidth’
‘aa’ ‘antialiased’

Thus you could abbreviate the above rc command as:

rc('lines', lw=2, c='r')

Note you can use python’s kwargs dictionary facility to store dictionaries of default parameters. e.g., you can customize the font rc as follows:

font = {'family' : 'monospace',
        'weight' : 'bold',
        'size'   : 'larger'}

rc('font', **font)  # pass in the font dict as kwargs

This enables you to easily switch between several configurations. Use rcdefaults() to restore the default rc params after changes.


Restore the default rc params. These are not the params loaded by the rc file, but mpl’s internal params. See rc_file_defaults for reloading the default params from the rc file

matplotlib.use(arg, warn=True, force=False)

Set the matplotlib backend to one of the known backends.

The argument is case-insensitive. warn specifies whether a warning should be issued if a backend has already been set up. force is an experimental flag that tells matplotlib to attempt to initialize a new backend by reloading the backend module.


This function must be called before importing pyplot for the first time; or, if you are not using pyplot, it must be called before importing matplotlib.backends. If warn is True, a warning is issued if you try and call this after pylab or pyplot have been loaded. In certain black magic use cases, e.g. pyplot.switch_backend(), we are doing the reloading necessary to make the backend switch work (in some cases, e.g., pure image backends) so one can set warn=False to suppress the warnings.

To find out which backend is currently set, see matplotlib.get_backend().