You are reading documentation for the unreleased version of Matplotlib. Try searching for the released version of this page instead?
Version 3.1.1.post1882+g70db457c3
matplotlib
Fork me on GitHub

Table of Contents

matplotlib

Backend management

matplotlib.use(backend, warn=<deprecated parameter>, force=True)[source]

Select the backend used for rendering and GUI integration.

Parameters:
backend : str

The backend to switch to. This can either be one of the standard backend names, which are case-insensitive:

  • interactive backends: GTK3Agg, GTK3Cairo, MacOSX, nbAgg, Qt4Agg, Qt4Cairo, Qt5Agg, Qt5Cairo, TkAgg, TkCairo, WebAgg, WX, WXAgg, WXCairo
  • non-interactive backends: agg, cairo, pdf, pgf, ps, svg, template

or a string of the form: module://my.module.name.

warn : bool, optional, default: False

If True and not force, emit a warning if a failure-to-switch ImportError has been suppressed. This parameter is deprecated.

force : bool, optional, 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, ignore the failure.

matplotlib.get_backend()[source]

Return the name of the current backend.

See also

matplotlib.use
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.

Default values and styling

matplotlib.rcParams

An instance of RcParams for handling default Matplotlib values.

class matplotlib.RcParams(*args, **kwargs)[source]

A dictionary object including validation.

Validating functions are defined and associated with rc parameters in matplotlib.rcsetup.

find_all(self, pattern)[source]

Return the subset of this RcParams dictionary whose keys match, using re.search(), the given pattern.

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 managing rc settings.

This allows one to do:

with mpl.rc_context(fname='screen.rc'):
    plt.plot(x, a)  # uses 'screen.rc'
    with mpl.rc_context(fname='print.rc'):
        plt.plot(x, b)  # uses 'print.rc'
    plt.plot(x, c)  # uses 'screen.rc'

A dictionary can also be passed to the context manager:

with mpl.rc_context(rc={'text.usetex': True}, fname='screen.rc'):
    plt.plot(x, a)

The 'rc' dictionary takes precedence over the settings loaded from 'fname'. Passing a dictionary only is also valid. For example a common usage is:

with mpl.rc_context(rc={'interactive': False}):
    fig, ax = plt.subplots()
    ax.plot(range(3), range(3))
    fig.savefig('A.png', format='png')
    plt.close(fig)
matplotlib.rc(group, **kwargs)[source]

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, e.g.,:

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 matplotlib.style.use('default') or rcdefaults() to restore the default rc params after changes.

Notes

Similar functionality is available by using the normal dict interface, i.e. rcParams.update({"lines.linewidth": 2, ...}) (but rcParams.update does not support abbreviations or grouping).

matplotlib.rcdefaults()[source]

Restore the rc params from Matplotlib's internal default style.

Style-blacklisted rc params (defined in matplotlib.style.core.STYLE_BLACKLIST) are not updated.

See also

rc_file_defaults
Restore the rc params 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 rc params from the original rc file loaded by Matplotlib.

Style-blacklisted rc params (defined in matplotlib.style.core.STYLE_BLACKLIST) are not updated.

matplotlib.rc_file(fname, *, use_default_template=True)[source]

Update rc params from file.

Style-blacklisted rc params (defined in matplotlib.style.core.STYLE_BLACKLIST) are not updated.

Parameters:
fname : str

Name of file parsed for matplotlib settings.

use_default_template : bool

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:
fname : str

Name of file parsed for Matplotlib settings.

fail_on_error : bool

If True, raise an error when the parser fails to convert a parameter.

use_default_template : bool

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.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 defined
  • Lastly, it looks in $MATPLOTLIBDATA/matplotlibrc, which should always exist.

Logging

matplotlib.set_loglevel(level)[source]

Sets the Matplotlib's root logger and root logger handler level, creating the handler if it does not exist yet.

Typically, one should call set_loglevel("info") or set_loglevel("debug") to get additional debugging information.

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.