.. _customizing-matplotlib:

**********************
Customizing matplotlib
**********************

.. _customizing-with-matplotlibrc-files:

The :file:`matplotlibrc` file
=============================

matplotlib uses :file:`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 :file:`matplotlibrc` in three
locations, in the following order:

1. :file:`matplotlibrc` in the current working directory, usually used for
   specific customizations that you do not want to apply elsewhere.
2. :file:`.matplotlib/matplotlibrc`, for the user's default customizations. See
   :ref:`locating-matplotlib-config-dir`.
3. :file:`{INSTALL}/matplotlib/mpl-data/matplotlibrc`, where :file:`{INSTALL}`
   is something like :file:`/usr/lib/python2.5/site-packages` on Linux, and
   maybe :file:`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 your :file:`.matplotlib`
   directory.

To display where the currently active :file:`matplotlibrc` file was
loaded from, one can do the following::

  >>> import matplotlib
  >>> matplotlib.matplotlib_fname()
  '/home/foo/.matplotlib/matplotlibrc'

See below for a sample :ref:`matplotlibrc file<matplotlibrc-sample>`.

.. _customizing-with-dynamic-rc-settings:

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 :data:`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 :func:`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 :func:`matplotlib.rcdefaults` command will restore the standard
matplotlib default settings.

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


.. _matplotlibrc-sample:

A sample matplotlibrc file
--------------------------------------------------------------------

.. htmlonly::

    `(download) <../_static/matplotlibrc>`__

.. literalinclude:: ../../lib/matplotlib/mpl-data/matplotlibrc