You are reading an old version of the documentation (v3.1.1). For the latest version see https://matplotlib.org/stable/api/matplotlib_configuration_api.html
Version 3.1.2
matplotlib
Fork me on GitHub

matplotlib

matplotlib.use(backend, warn=False, 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, warn that the call will have no effect if this is called after pyplot has been imported and a backend is set up.

force : bool, optional, default: True

If True, attempt to switch the backend. An ImportError is raised if an interactive backend is selected, but another interactive backend has already started.

matplotlib.get_backend()[source]

Return the name of the current backend.

See also

matplotlib.use
matplotlib.rcParams

An instance of RcParams for handling default matplotlib values.

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)
    with mpl.rc_context(fname='print.rc'):
        plt.plot(x, b)
    plt.plot(x, c)

The 'a' vs 'x' and 'c' vs 'x' plots would have settings from 'screen.rc', while the 'b' vs 'x' plot would have settings from 'print.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.

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

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

A dictionary object including validation

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

copy(self)[source]
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.

msg_backend_obsolete
msg_depr
msg_depr_ignore
msg_depr_set
msg_obsolete
validate = {'_internal.classic_mode': <function validate_bool>, 'agg.path.chunksize': <function validate_int>, 'animation.avconv_args': <function _listify_validator.<locals>.f>, 'animation.avconv_path': <function validate_animation_writer_path>, 'animation.bitrate': <function validate_int>, 'animation.codec': <function validate_string>, 'animation.convert_args': <function _listify_validator.<locals>.f>, 'animation.convert_path': <function validate_animation_writer_path>, 'animation.embed_limit': <function validate_float>, 'animation.ffmpeg_args': <function _listify_validator.<locals>.f>, 'animation.ffmpeg_path': <function validate_animation_writer_path>, 'animation.frame_format': <matplotlib.rcsetup.ValidateInStrings object>, 'animation.html': <matplotlib.rcsetup.ValidateInStrings object>, 'animation.html_args': <function _listify_validator.<locals>.f>, 'animation.writer': <matplotlib.rcsetup.ValidateInStrings object>, 'axes.autolimit_mode': <matplotlib.rcsetup.ValidateInStrings object>, 'axes.axisbelow': <function validate_axisbelow>, 'axes.edgecolor': <function validate_color>, 'axes.facecolor': <function validate_color>, 'axes.formatter.limits': <matplotlib.rcsetup.validate_nseq_int object>, 'axes.formatter.min_exponent': <function validate_int>, 'axes.formatter.offset_threshold': <function validate_int>, 'axes.formatter.use_locale': <function validate_bool>, 'axes.formatter.use_mathtext': <function validate_bool>, 'axes.formatter.useoffset': <function validate_bool>, 'axes.grid': <function validate_bool>, 'axes.grid.axis': <matplotlib.rcsetup.ValidateInStrings object>, 'axes.grid.which': <matplotlib.rcsetup.ValidateInStrings object>, 'axes.labelcolor': <function validate_color>, 'axes.labelpad': <function validate_float>, 'axes.labelsize': <function validate_fontsize>, 'axes.labelweight': <function validate_fontweight>, 'axes.linewidth': <function validate_float>, 'axes.prop_cycle': <function validate_cycler>, 'axes.spines.bottom': <function validate_bool>, 'axes.spines.left': <function validate_bool>, 'axes.spines.right': <function validate_bool>, 'axes.spines.top': <function validate_bool>, 'axes.titlepad': <function validate_float>, 'axes.titlesize': <function validate_fontsize>, 'axes.titleweight': <function validate_fontweight>, 'axes.unicode_minus': <function validate_bool>, 'axes.xmargin': <matplotlib.rcsetup.ValidateInterval object>, 'axes.ymargin': <matplotlib.rcsetup.ValidateInterval object>, 'axes3d.grid': <function validate_bool>, 'backend': <function validate_backend>, 'backend_fallback': <function validate_bool>, 'boxplot.bootstrap': <function validate_int_or_None>, 'boxplot.boxprops.color': <function validate_color>, 'boxplot.boxprops.linestyle': <function _validate_linestyle>, 'boxplot.boxprops.linewidth': <function validate_float>, 'boxplot.capprops.color': <function validate_color>, 'boxplot.capprops.linestyle': <function _validate_linestyle>, 'boxplot.capprops.linewidth': <function validate_float>, 'boxplot.flierprops.color': <function validate_color>, 'boxplot.flierprops.linestyle': <function _validate_linestyle>, 'boxplot.flierprops.linewidth': <function validate_float>, 'boxplot.flierprops.marker': <function validate_string>, 'boxplot.flierprops.markeredgecolor': <function validate_color>, 'boxplot.flierprops.markeredgewidth': <function validate_float>, 'boxplot.flierprops.markerfacecolor': <function validate_color_or_auto>, 'boxplot.flierprops.markersize': <function validate_float>, 'boxplot.meanline': <function validate_bool>, 'boxplot.meanprops.color': <function validate_color>, 'boxplot.meanprops.linestyle': <function _validate_linestyle>, 'boxplot.meanprops.linewidth': <function validate_float>, 'boxplot.meanprops.marker': <function validate_string>, 'boxplot.meanprops.markeredgecolor': <function validate_color>, 'boxplot.meanprops.markerfacecolor': <function validate_color>, 'boxplot.meanprops.markersize': <function validate_float>, 'boxplot.medianprops.color': <function validate_color>, 'boxplot.medianprops.linestyle': <function _validate_linestyle>, 'boxplot.medianprops.linewidth': <function validate_float>, 'boxplot.notch': <function validate_bool>, 'boxplot.patchartist': <function validate_bool>, 'boxplot.showbox': <function validate_bool>, 'boxplot.showcaps': <function validate_bool>, 'boxplot.showfliers': <function validate_bool>, 'boxplot.showmeans': <function validate_bool>, 'boxplot.vertical': <function validate_bool>, 'boxplot.whiskerprops.color': <function validate_color>, 'boxplot.whiskerprops.linestyle': <function _validate_linestyle>, 'boxplot.whiskerprops.linewidth': <function validate_float>, 'boxplot.whiskers': <function validate_whiskers>, 'contour.corner_mask': <function validate_bool>, 'contour.negative_linestyle': <function _validate_linestyle>, 'datapath': <function validate_path_exists>, 'date.autoformatter.day': <function validate_string>, 'date.autoformatter.hour': <function validate_string>, 'date.autoformatter.microsecond': <function validate_string>, 'date.autoformatter.minute': <function validate_string>, 'date.autoformatter.month': <function validate_string>, 'date.autoformatter.second': <function validate_string>, 'date.autoformatter.year': <function validate_string>, 'docstring.hardcopy': <function validate_bool>, 'errorbar.capsize': <function validate_float>, 'examples.directory': <function validate_string>, 'figure.autolayout': <function validate_bool>, 'figure.constrained_layout.h_pad': <function validate_float>, 'figure.constrained_layout.hspace': <matplotlib.rcsetup.ValidateInterval object>, 'figure.constrained_layout.use': <function validate_bool>, 'figure.constrained_layout.w_pad': <function validate_float>, 'figure.constrained_layout.wspace': <matplotlib.rcsetup.ValidateInterval object>, 'figure.dpi': <function validate_float>, 'figure.edgecolor': <function validate_color>, 'figure.facecolor': <function validate_color>, 'figure.figsize': <matplotlib.rcsetup.validate_nseq_float object>, 'figure.frameon': <function validate_bool>, 'figure.max_open_warning': <function validate_int>, 'figure.subplot.bottom': <matplotlib.rcsetup.ValidateInterval object>, 'figure.subplot.hspace': <matplotlib.rcsetup.ValidateInterval object>, 'figure.subplot.left': <matplotlib.rcsetup.ValidateInterval object>, 'figure.subplot.right': <matplotlib.rcsetup.ValidateInterval object>, 'figure.subplot.top': <matplotlib.rcsetup.ValidateInterval object>, 'figure.subplot.wspace': <matplotlib.rcsetup.ValidateInterval object>, 'figure.titlesize': <function validate_fontsize>, 'figure.titleweight': <function validate_fontweight>, 'font.cursive': <function _listify_validator.<locals>.f>, 'font.family': <function _listify_validator.<locals>.f>, 'font.fantasy': <function _listify_validator.<locals>.f>, 'font.monospace': <function _listify_validator.<locals>.f>, 'font.sans-serif': <function _listify_validator.<locals>.f>, 'font.serif': <function _listify_validator.<locals>.f>, 'font.size': <function validate_float>, 'font.stretch': <function validate_string>, 'font.style': <function validate_string>, 'font.variant': <function validate_string>, 'font.weight': <function validate_fontweight>, 'grid.alpha': <function validate_float>, 'grid.color': <function validate_color>, 'grid.linestyle': <function _validate_linestyle>, 'grid.linewidth': <function validate_float>, 'hatch.color': <function validate_color>, 'hatch.linewidth': <function validate_float>, 'hist.bins': <function validate_hist_bins>, 'image.aspect': <function validate_aspect>, 'image.cmap': <function validate_string>, 'image.composite_image': <function validate_bool>, 'image.interpolation': <function validate_string>, 'image.lut': <function validate_int>, 'image.origin': <matplotlib.rcsetup.ValidateInStrings object>, 'image.resample': <function validate_bool>, 'interactive': <function validate_bool>, 'keymap.all_axes': <function _listify_validator.<locals>.f>, 'keymap.back': <function _listify_validator.<locals>.f>, 'keymap.copy': <function _listify_validator.<locals>.f>, 'keymap.forward': <function _listify_validator.<locals>.f>, 'keymap.fullscreen': <function _listify_validator.<locals>.f>, 'keymap.grid': <function _listify_validator.<locals>.f>, 'keymap.grid_minor': <function _listify_validator.<locals>.f>, 'keymap.help': <function _listify_validator.<locals>.f>, 'keymap.home': <function _listify_validator.<locals>.f>, 'keymap.pan': <function _listify_validator.<locals>.f>, 'keymap.quit': <function _listify_validator.<locals>.f>, 'keymap.quit_all': <function _listify_validator.<locals>.f>, 'keymap.save': <function _listify_validator.<locals>.f>, 'keymap.xscale': <function _listify_validator.<locals>.f>, 'keymap.yscale': <function _listify_validator.<locals>.f>, 'keymap.zoom': <function _listify_validator.<locals>.f>, 'legend.borderaxespad': <function validate_float>, 'legend.borderpad': <function validate_float>, 'legend.columnspacing': <function validate_float>, 'legend.edgecolor': <function validate_color_or_inherit>, 'legend.facecolor': <function validate_color_or_inherit>, 'legend.fancybox': <function validate_bool>, 'legend.fontsize': <function validate_fontsize>, 'legend.framealpha': <function validate_float_or_None>, 'legend.frameon': <function validate_bool>, 'legend.handleheight': <function validate_float>, 'legend.handlelength': <function validate_float>, 'legend.handletextpad': <function validate_float>, 'legend.labelspacing': <function validate_float>, 'legend.loc': <matplotlib.rcsetup.ValidateInStrings object>, 'legend.markerscale': <function validate_float>, 'legend.numpoints': <function validate_int>, 'legend.scatterpoints': <function validate_int>, 'legend.shadow': <function validate_bool>, 'legend.title_fontsize': <function validate_fontsize_None>, 'lines.antialiased': <function validate_bool>, 'lines.color': <function validate_color>, 'lines.dash_capstyle': <matplotlib.rcsetup.ValidateInStrings object>, 'lines.dash_joinstyle': <matplotlib.rcsetup.ValidateInStrings object>, 'lines.dashdot_pattern': <matplotlib.rcsetup.validate_nseq_float object>, 'lines.dashed_pattern': <matplotlib.rcsetup.validate_nseq_float object>, 'lines.dotted_pattern': <matplotlib.rcsetup.validate_nseq_float object>, 'lines.linestyle': <function _validate_linestyle>, 'lines.linewidth': <function validate_float>, 'lines.marker': <function validate_string>, 'lines.markeredgecolor': <function validate_color_or_auto>, 'lines.markeredgewidth': <function validate_float>, 'lines.markerfacecolor': <function validate_color_or_auto>, 'lines.markersize': <function validate_float>, 'lines.scale_dashes': <function validate_bool>, 'lines.solid_capstyle': <matplotlib.rcsetup.ValidateInStrings object>, 'lines.solid_joinstyle': <matplotlib.rcsetup.ValidateInStrings object>, 'markers.fillstyle': <matplotlib.rcsetup.ValidateInStrings object>, 'mathtext.bf': <function validate_font_properties>, 'mathtext.cal': <function validate_font_properties>, 'mathtext.default': <function validate_mathtext_default>, 'mathtext.fallback_to_cm': <function validate_bool>, 'mathtext.fontset': <matplotlib.rcsetup.ValidateInStrings object>, 'mathtext.it': <function validate_font_properties>, 'mathtext.rm': <function validate_font_properties>, 'mathtext.sf': <function validate_font_properties>, 'mathtext.tt': <function validate_font_properties>, 'patch.antialiased': <function validate_bool>, 'patch.edgecolor': <function validate_color>, 'patch.facecolor': <function validate_color>, 'patch.force_edgecolor': <function validate_bool>, 'patch.linewidth': <function validate_float>, 'path.effects': <function validate_any>, 'path.simplify': <function validate_bool>, 'path.simplify_threshold': <matplotlib.rcsetup.ValidateInterval object>, 'path.sketch': <function validate_sketch>, 'path.snap': <function validate_bool>, 'pdf.compression': <function validate_int>, 'pdf.fonttype': <function validate_fonttype>, 'pdf.inheritcolor': <function validate_bool>, 'pdf.use14corefonts': <function validate_bool>, 'pgf.preamble': <function _validate_tex_preamble>, 'pgf.rcfonts': <function validate_bool>, 'pgf.texsystem': <matplotlib.rcsetup.ValidateInStrings object>, 'polaraxes.grid': <function validate_bool>, 'ps.distiller.res': <function validate_int>, 'ps.fonttype': <function validate_fonttype>, 'ps.papersize': <matplotlib.rcsetup.ValidateInStrings object>, 'ps.useafm': <function validate_bool>, 'ps.usedistiller': <function validate_ps_distiller>, 'savefig.bbox': <function validate_bbox>, 'savefig.directory': <function validate_string>, 'savefig.dpi': <function validate_dpi>, 'savefig.edgecolor': <function validate_color>, 'savefig.facecolor': <function validate_color>, 'savefig.format': <function update_savefig_format>, 'savefig.frameon': <function validate_bool>, 'savefig.jpeg_quality': <function validate_int>, 'savefig.orientation': <matplotlib.rcsetup.ValidateInStrings object>, 'savefig.pad_inches': <function validate_float>, 'savefig.transparent': <function validate_bool>, 'scatter.edgecolors': <function validate_string>, 'scatter.marker': <function validate_string>, 'svg.fonttype': <function validate_svg_fonttype>, 'svg.hashsalt': <function validate_string_or_None>, 'svg.image_inline': <function validate_bool>, 'text.antialiased': <function validate_bool>, 'text.color': <function validate_color>, 'text.hinting': <function validate_hinting>, 'text.hinting_factor': <function validate_int>, 'text.latex.preamble': <function _validate_tex_preamble>, 'text.latex.preview': <function validate_bool>, 'text.latex.unicode': <function validate_bool>, 'text.usetex': <function validate_bool>, 'timezone': <function validate_string>, 'tk.window_focus': <function validate_bool>, 'toolbar': <function validate_toolbar>, 'verbose.fileo': <function validate_string>, 'verbose.level': <matplotlib.rcsetup.ValidateInStrings object>, 'webagg.address': <function validate_webagg_address>, 'webagg.open_in_browser': <function validate_bool>, 'webagg.port': <function validate_int>, 'webagg.port_retries': <function validate_int>, 'xtick.alignment': <matplotlib.rcsetup.ValidateInStrings object>, 'xtick.bottom': <function validate_bool>, 'xtick.color': <function validate_color>, 'xtick.direction': <function validate_string>, 'xtick.labelbottom': <function validate_bool>, 'xtick.labelsize': <function validate_fontsize>, 'xtick.labeltop': <function validate_bool>, 'xtick.major.bottom': <function validate_bool>, 'xtick.major.pad': <function validate_float>, 'xtick.major.size': <function validate_float>, 'xtick.major.top': <function validate_bool>, 'xtick.major.width': <function validate_float>, 'xtick.minor.bottom': <function validate_bool>, 'xtick.minor.pad': <function validate_float>, 'xtick.minor.size': <function validate_float>, 'xtick.minor.top': <function validate_bool>, 'xtick.minor.visible': <function validate_bool>, 'xtick.minor.width': <function validate_float>, 'xtick.top': <function validate_bool>, 'ytick.alignment': <matplotlib.rcsetup.ValidateInStrings object>, 'ytick.color': <function validate_color>, 'ytick.direction': <function validate_string>, 'ytick.labelleft': <function validate_bool>, 'ytick.labelright': <function validate_bool>, 'ytick.labelsize': <function validate_fontsize>, 'ytick.left': <function validate_bool>, 'ytick.major.left': <function validate_bool>, 'ytick.major.pad': <function validate_float>, 'ytick.major.right': <function validate_bool>, 'ytick.major.size': <function validate_float>, 'ytick.major.width': <function validate_float>, 'ytick.minor.left': <function validate_bool>, 'ytick.minor.pad': <function validate_float>, 'ytick.minor.right': <function validate_bool>, 'ytick.minor.size': <function validate_float>, 'ytick.minor.visible': <function validate_bool>, 'ytick.minor.width': <function validate_float>, 'ytick.right': <function validate_bool>}
matplotlib.rc_params(fail_on_error=False)[source]

Return a matplotlib.RcParams instance from the default matplotlib rc file.

matplotlib.rc_params_from_file(fname, fail_on_error=False, use_default_template=True)[source]

Return matplotlib.RcParams from the contents of the given file.

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.
matplotlib.interactive(b)[source]

Set interactive mode to boolean b.

If b is True, then draw after every plotting command, e.g., after xlabel

matplotlib.is_interactive()[source]

Return true if plot mode is interactive

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.