### Navigation

- index
- modules |
- next |
- previous |
- home|
- examples|
- tutorials|
- pyplot|
- docs »
- The Matplotlib API »

# The top level `matplotlib` module

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

  Note

  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()`.

`matplotlib.``get_backend`()

  Return the name of the current backend.

`matplotlib.``rcParams`

  An instance of `RcParams` for handling default matplotlib values.

`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, 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.``matplotlib_fname`()

  Get the location of the config file.

  The file location is determined in the following order

  - `$PWD/matplotlibrc`

  - `$MATPLOTLIBRC` if it is a file

  - `$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` for a system-defined copy.

class `matplotlib.``RcParams`(*args, **kwargs)

  A dictionary object including validation

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

`matplotlib.``rc_params`(fail_on_error=False)

  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)

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

class `matplotlib.``rc_context`(rc=None, fname=None)

  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)