matplotlib
#
An object-oriented plotting library.
A procedural interface is provided by the companion pyplot module, which may be imported directly, e.g.:
import matplotlib.pyplot as plt
or using ipython:
ipython
at your terminal, followed by:
In [1]: %matplotlib
In [2]: import matplotlib.pyplot as plt
at the ipython shell prompt.
For the most part, direct use of the explicit object-oriented library is
encouraged when programming; the implicit pyplot interface is primarily for
working interactively. The exceptions to this suggestion are the pyplot
functions pyplot.figure
, pyplot.subplot
, pyplot.subplots
, and
pyplot.savefig
, which can greatly simplify scripting. See
Matplotlib Application Interfaces (APIs) for an explanation of the tradeoffs between the implicit
and explicit interfaces.
Modules include:
matplotlib.axes
The
Axes
class. Most pyplot functions are wrappers forAxes
methods. The axes module is the highest level of OO access to the library.matplotlib.figure
The
Figure
class.matplotlib.artist
The
Artist
base class for all classes that draw things.matplotlib.lines
The
Line2D
class for drawing lines and markers.matplotlib.patches
Classes for drawing polygons.
matplotlib.text
The
Text
andAnnotation
classes.matplotlib.image
The
AxesImage
andFigureImage
classes.matplotlib.collections
Classes for efficient drawing of groups of lines or polygons.
matplotlib.colors
Color specifications and making colormaps.
matplotlib.cm
Colormaps, and the
ScalarMappable
mixin class for providing color mapping functionality to other classes.matplotlib.ticker
Calculation of tick mark locations and formatting of tick labels.
matplotlib.backends
A subpackage with modules for various GUI libraries and output formats.
The base matplotlib namespace includes:
The following environment variables can be used to customize the behavior:
MPLBACKEND
This optional variable can be set to choose the Matplotlib backend. See What is a backend?.
MPLCONFIGDIR
This is the directory used to store user customizations to Matplotlib, as well as some caches to improve performance. If
MPLCONFIGDIR
is not defined,HOME/.config/matplotlib
andHOME/.cache/matplotlib
are used on Linux, andHOME/.matplotlib
on other platforms, if they are writable. Otherwise, the Python standard library'stempfile.gettempdir
is used to find a base directory in which thematplotlib
subdirectory is created.
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.
Backend management#
- matplotlib.use(backend, *, force=True)[source]#
Select the backend used for rendering and GUI integration.
If pyplot is already imported,
switch_backend
is used and if the new backend is different than the current backend, all Figures will be closed.- Parameters:
- backendstr
The backend to switch to. This can either be one of the standard backend names, which are case-insensitive:
interactive backends: GTK3Agg, GTK3Cairo, GTK4Agg, GTK4Cairo, MacOSX, nbAgg, QtAgg, QtCairo, TkAgg, TkCairo, WebAgg, WX, WXAgg, WXCairo, Qt5Agg, Qt5Cairo
non-interactive backends: agg, cairo, pdf, pgf, ps, svg, template
or a string of the form:
module://my.module.name
.Switching to an interactive backend is not possible if an unrelated event loop has already been started (e.g., switching to GTK3Agg if a TkAgg window has already been opened). Switching to a non-interactive backend is always possible.
- forcebool, default: True
If True (the default), raise an
ImportError
if the backend cannot be set up (either because it fails to import, or because an incompatible GUI interactive framework is already running); if False, silently ignore the failure.
- matplotlib.interactive(b)[source]#
Set whether to redraw after every plotting command (e.g.
pyplot.xlabel
).
- matplotlib.is_interactive()[source]#
Return whether to redraw after every plotting command.
Note
This function is only intended for use in backends. End users should use
pyplot.isinteractive
instead.
Default values and styling#
- class matplotlib.RcParams(*args, **kwargs)[source]#
A dict-like key-value store for config parameters, including validation.
Validating functions are defined and associated with rc parameters in
matplotlib.rcsetup
.The list of rcParams is:
_internal.classic_mode
agg.path.chunksize
animation.bitrate
animation.codec
animation.convert_args
animation.convert_path
animation.embed_limit
animation.ffmpeg_args
animation.ffmpeg_path
animation.frame_format
animation.html
animation.writer
axes.autolimit_mode
axes.axisbelow
axes.edgecolor
axes.facecolor
axes.formatter.limits
axes.formatter.min_exponent
axes.formatter.offset_threshold
axes.formatter.use_locale
axes.formatter.use_mathtext
axes.formatter.useoffset
axes.grid
axes.grid.axis
axes.grid.which
axes.labelcolor
axes.labelpad
axes.labelsize
axes.labelweight
axes.linewidth
axes.prop_cycle
axes.spines.bottom
axes.spines.left
axes.spines.right
axes.spines.top
axes.titlecolor
axes.titlelocation
axes.titlepad
axes.titlesize
axes.titleweight
axes.titley
axes.unicode_minus
axes.xmargin
axes.ymargin
axes.zmargin
axes3d.grid
axes3d.xaxis.panecolor
axes3d.yaxis.panecolor
axes3d.zaxis.panecolor
backend
backend_fallback
boxplot.bootstrap
boxplot.boxprops.color
boxplot.boxprops.linestyle
boxplot.boxprops.linewidth
boxplot.capprops.color
boxplot.capprops.linestyle
boxplot.capprops.linewidth
boxplot.flierprops.color
boxplot.flierprops.linestyle
boxplot.flierprops.linewidth
boxplot.flierprops.marker
boxplot.flierprops.markeredgecolor
boxplot.flierprops.markeredgewidth
boxplot.flierprops.markerfacecolor
boxplot.flierprops.markersize
boxplot.meanline
boxplot.meanprops.color
boxplot.meanprops.linestyle
boxplot.meanprops.linewidth
boxplot.meanprops.marker
boxplot.meanprops.markeredgecolor
boxplot.meanprops.markerfacecolor
boxplot.meanprops.markersize
boxplot.medianprops.color
boxplot.medianprops.linestyle
boxplot.medianprops.linewidth
boxplot.notch
boxplot.patchartist
boxplot.showbox
boxplot.showcaps
boxplot.showfliers
boxplot.showmeans
boxplot.vertical
boxplot.whiskerprops.color
boxplot.whiskerprops.linestyle
boxplot.whiskerprops.linewidth
boxplot.whiskers
contour.algorithm
contour.corner_mask
contour.linewidth
contour.negative_linestyle
date.autoformatter.day
date.autoformatter.hour
date.autoformatter.microsecond
date.autoformatter.minute
date.autoformatter.month
date.autoformatter.second
date.autoformatter.year
date.converter
date.epoch
date.interval_multiples
docstring.hardcopy
errorbar.capsize
figure.autolayout
figure.constrained_layout.h_pad
figure.constrained_layout.hspace
figure.constrained_layout.use
figure.constrained_layout.w_pad
figure.constrained_layout.wspace
figure.dpi
figure.edgecolor
figure.facecolor
figure.figsize
figure.frameon
figure.hooks
figure.labelsize
figure.labelweight
figure.max_open_warning
figure.raise_window
figure.subplot.bottom
figure.subplot.hspace
figure.subplot.left
figure.subplot.right
figure.subplot.top
figure.subplot.wspace
figure.titlesize
figure.titleweight
font.cursive
font.family
font.fantasy
font.monospace
font.sans-serif
font.serif
font.size
font.stretch
font.style
font.variant
font.weight
grid.alpha
grid.color
grid.linestyle
grid.linewidth
hatch.color
hatch.linewidth
hist.bins
image.aspect
image.cmap
image.composite_image
image.interpolation
image.lut
image.origin
image.resample
interactive
keymap.back
keymap.copy
keymap.forward
keymap.fullscreen
keymap.grid
keymap.grid_minor
keymap.help
keymap.home
keymap.pan
keymap.quit
keymap.quit_all
keymap.save
keymap.xscale
keymap.yscale
keymap.zoom
legend.borderaxespad
legend.borderpad
legend.columnspacing
legend.edgecolor
legend.facecolor
legend.fancybox
legend.fontsize
legend.framealpha
legend.frameon
legend.handleheight
legend.handlelength
legend.handletextpad
legend.labelcolor
legend.labelspacing
legend.loc
legend.markerscale
legend.numpoints
legend.scatterpoints
legend.shadow
legend.title_fontsize
lines.antialiased
lines.color
lines.dash_capstyle
lines.dash_joinstyle
lines.dashdot_pattern
lines.dashed_pattern
lines.dotted_pattern
lines.linestyle
lines.linewidth
lines.marker
lines.markeredgecolor
lines.markeredgewidth
lines.markerfacecolor
lines.markersize
lines.scale_dashes
lines.solid_capstyle
lines.solid_joinstyle
markers.fillstyle
mathtext.bf
mathtext.cal
mathtext.default
mathtext.fallback
mathtext.fontset
mathtext.it
mathtext.rm
mathtext.sf
mathtext.tt
patch.antialiased
patch.edgecolor
patch.facecolor
patch.force_edgecolor
patch.linewidth
path.effects
path.simplify
path.simplify_threshold
path.sketch
path.snap
pcolor.shading
pcolormesh.snap
pdf.compression
pdf.fonttype
pdf.inheritcolor
pdf.use14corefonts
pgf.preamble
pgf.rcfonts
pgf.texsystem
polaraxes.grid
ps.distiller.res
ps.fonttype
ps.papersize
ps.useafm
ps.usedistiller
savefig.bbox
savefig.directory
savefig.dpi
savefig.edgecolor
savefig.facecolor
savefig.format
savefig.orientation
savefig.pad_inches
savefig.transparent
scatter.edgecolors
scatter.marker
svg.fonttype
svg.hashsalt
svg.image_inline
text.antialiased
text.color
text.hinting
text.hinting_factor
text.kerning_factor
text.latex.preamble
text.parse_math
text.usetex
timezone
tk.window_focus
toolbar
webagg.address
webagg.open_in_browser
webagg.port
webagg.port_retries
xaxis.labellocation
xtick.alignment
xtick.bottom
xtick.color
xtick.direction
xtick.labelbottom
xtick.labelcolor
xtick.labelsize
xtick.labeltop
xtick.major.bottom
xtick.major.pad
xtick.major.size
xtick.major.top
xtick.major.width
xtick.minor.bottom
xtick.minor.pad
xtick.minor.size
xtick.minor.top
xtick.minor.visible
xtick.minor.width
xtick.top
yaxis.labellocation
ytick.alignment
ytick.color
ytick.direction
ytick.labelcolor
ytick.labelleft
ytick.labelright
ytick.labelsize
ytick.left
ytick.major.left
ytick.major.pad
ytick.major.right
ytick.major.size
ytick.major.width
ytick.minor.left
ytick.minor.pad
ytick.minor.right
ytick.minor.size
ytick.minor.visible
ytick.minor.width
ytick.right
See also
- find_all(pattern)[source]#
Return the subset of this RcParams dictionary whose keys match, using
re.search()
, the givenpattern
.Note
Changes to the returned dictionary are not propagated to the parent RcParams dictionary.
- matplotlib.rc_context(rc=None, fname=None)[source]#
Return a context manager for temporarily changing rcParams.
The
rcParams["backend"]
will not be reset by the context manager.rcParams changed both through the context manager invocation and in the body of the context will be reset on context exit.
- Parameters:
- rcdict
The rcParams to temporarily set.
- fnamestr or path-like
A file with Matplotlib rc settings. If both fname and rc are given, settings from rc take precedence.
See also
Examples
Passing explicit values via a dict:
with mpl.rc_context({'interactive': False}): fig, ax = plt.subplots() ax.plot(range(3), range(3)) fig.savefig('example.png') plt.close(fig)
Loading settings from a file:
with mpl.rc_context(fname='print.rc'): plt.plot(x, y) # uses 'print.rc'
Setting in the context body:
with mpl.rc_context(): # will be reset mpl.rcParams['lines.linewidth'] = 5 plt.plot(x, y)
- matplotlib.rc(group, **kwargs)[source]#
Set the current
rcParams
. group is the grouping for the rc, e.g., forlines.linewidth
the group islines
, foraxes.facecolor
, the group isaxes
, 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, e.g.,:rc('lines', linewidth=2, color='r')
sets the current
rcParams
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 call 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
matplotlib.style.use('default')
orrcdefaults()
to restore the defaultrcParams
after changes.Notes
Similar functionality is available by using the normal dict interface, i.e.
rcParams.update({"lines.linewidth": 2, ...})
(butrcParams.update
does not support abbreviations or grouping).
- matplotlib.rcdefaults()[source]#
Restore the
rcParams
from Matplotlib's internal default style.Style-blacklisted
rcParams
(defined inmatplotlib.style.core.STYLE_BLACKLIST
) are not updated.See also
matplotlib.rc_file_defaults
Restore the
rcParams
from the rc file originally loaded by Matplotlib.matplotlib.style.use
Use a specific style file. Call
style.use('default')
to restore the default style.
- matplotlib.rc_file_defaults()[source]#
Restore the
rcParams
from the original rc file loaded by Matplotlib.Style-blacklisted
rcParams
(defined inmatplotlib.style.core.STYLE_BLACKLIST
) are not updated.
- matplotlib.rc_file(fname, *, use_default_template=True)[source]#
Update
rcParams
from file.Style-blacklisted
rcParams
(defined inmatplotlib.style.core.STYLE_BLACKLIST
) are not updated.- Parameters:
- fnamestr or path-like
A file with Matplotlib rc settings.
- use_default_templatebool
If True, initialize with default parameters before updating with those in the given file. If False, the current configuration persists and only the parameters specified in the file are updated.
- matplotlib.rc_params(fail_on_error=False)[source]#
Construct a
RcParams
instance from the default Matplotlib rc file.
- matplotlib.rc_params_from_file(fname, fail_on_error=False, use_default_template=True)[source]#
Construct a
RcParams
from file fname.- Parameters:
- fnamestr or path-like
A file with Matplotlib rc settings.
- fail_on_errorbool
If True, raise an error when the parser fails to convert a parameter.
- use_default_templatebool
If True, initialize with default parameters before updating with those in the given file. If False, the configuration class only contains the parameters specified in the file. (Useful for updating dicts.)
- matplotlib.get_configdir()[source]#
Return the string path of the configuration directory.
The directory is chosen as follows:
If the MPLCONFIGDIR environment variable is supplied, choose that.
On Linux, follow the XDG specification and look first in
$XDG_CONFIG_HOME
, if defined, or$HOME/.config
. On other platforms, choose$HOME/.matplotlib
.If the chosen directory exists and is writable, use that as the configuration directory.
Else, create a temporary directory, and use it as the configuration directory.
- matplotlib.matplotlib_fname()[source]#
Get the location of the config file.
The file location is determined in the following order
$PWD/matplotlibrc
$MATPLOTLIBRC
if it is not a directory$MATPLOTLIBRC/matplotlibrc
$MPLCONFIGDIR/matplotlibrc
- On Linux,
$XDG_CONFIG_HOME/matplotlib/matplotlibrc
(if$XDG_CONFIG_HOME
is defined)or
$HOME/.config/matplotlib/matplotlibrc
(if$XDG_CONFIG_HOME
is not defined)
On other platforms, -
$HOME/.matplotlib/matplotlibrc
if$HOME
is definedLastly, it looks in
$MATPLOTLIBDATA/matplotlibrc
, which should always exist.
Logging#
- matplotlib.set_loglevel(level)[source]#
Configure Matplotlib's logging levels.
Matplotlib uses the standard library
logging
framework under the root logger 'matplotlib'. This is a helper function to:set Matplotlib's root logger level
set the root logger handler's level, creating the handler if it does not exist yet
Typically, one should call
set_loglevel("info")
orset_loglevel("debug")
to get additional debugging information.Users or applications that are installing their own logging handlers may want to directly manipulate
logging.getLogger('matplotlib')
rather than use this function.- Parameters:
- level{"notset", "debug", "info", "warning", "error", "critical"}
The log level of the handler.
Notes
The first time this function is called, an additional handler is attached to Matplotlib's root handler; this handler is reused every time and this function simply manipulates the logger and handler's level.
Colormaps and color sequences#
- matplotlib.colormaps[source]#
Container for colormaps that are known to Matplotlib by name.
The universal registry instance is
matplotlib.colormaps
. There should be no need for users to instantiateColormapRegistry
themselves.Read access uses a dict-like interface mapping names to
Colormap
s:import matplotlib as mpl cmap = mpl.colormaps['viridis']
Returned
Colormap
s are copies, so that their modification does not change the global definition of the colormap.Additional colormaps can be added via
ColormapRegistry.register
:mpl.colormaps.register(my_colormap)
- matplotlib.color_sequences[source]#
Container for sequences of colors that are known to Matplotlib by name.
The universal registry instance is
matplotlib.color_sequences
. There should be no need for users to instantiateColorSequenceRegistry
themselves.Read access uses a dict-like interface mapping names to lists of colors:
import matplotlib as mpl cmap = mpl.color_sequences['tab10']
The returned lists are copies, so that their modification does not change the global definition of the color sequence.
Additional color sequences can be added via
ColorSequenceRegistry.register
:mpl.color_sequences.register('rgb', ['r', 'g', 'b'])