Customizing matplotlib

The matplotlibrc file

matplotlib uses matplotlibrc configuration files to customize all kinds of properties, which we call rc settings or rc parameters. You can control the defaults of almost every property in matplotlib: figure size and dpi, line width, color and style, axes, axis and grid properties, text and font properties and so on. matplotlib looks for matplotlibrc in three locations, in the following order:

  1. matplotlibrc in the current working directory, usually used for specific customizations that you do not want to apply elsewhere.
  2. .matplotlib/matplotlibrc, for the user’s default customizations. See Where is my .matplotlib directory?.
  3. INSTALL/matplotlib/mpl-data/matplotlibrc, where INSTALL is something like /usr/lib/python2.5/site-packages on Linux, and maybe C:\Python25\Lib\site-packages on Windows. Every time you install matplotlib, this file will be overwritten, so if you want your customizations to be saved, please move this file to you .matplotlib directory.

See below for a sample matplotlibrc file.

Dynamic rc settings

You can also dynamically change the default rc settings in a python script or interactively from the python shell. All of the rc settings are stored in a dictionary-like variable called matplotlib.rcParams, which is global to the matplotlib package. rcParams can be modified directly, for example:

import matplotlib as mpl
mpl.rcParams['lines.linewidth'] = 2
mpl.rcParams['lines.color'] = 'r'

Matplotlib also provides a couple of convenience functions for modifying rc settings. The matplotlib.rc() command can be used to modify multiple settings in a single group at once, using keyword arguments:

import matplotlib as mpl
mpl.rc('lines', linewidth=2, color='r')

There matplotlib.rcdefaults() command will restore the standard matplotlib default settings.

There is some degree of validation when setting the values of rcParams, see matplotlib.rcsetup for details.

A sample matplotlibrc file

System Message: WARNING/2 (/build/buildd/matplotlib-0.98.3/doc/users/customizing.rst, line 66)

Include file u’../mpl_data/matplotlibrc’ not found or reading it failed