We've just covered some examples of matplotlib customization. Hand in hand with this topic is that of configuration—the tweaking of predefined values to override default behaviors. The matplotlib module offers two ways to override the default values for the configuration settings—you can either run the control files, or run the control parameters that are stored in-memory to make changes to a running instance.
While commonly expanded to the run control, the .rc
extension and -rc
suffix trace their origins to 1965 and the
Multics (short for Multiplexed Information and Computing Service) operating system, where rc
stood for the run command. Like many software systems that were developed on UNIX- or BSD-based machines, matplotlib has an rc
file where the control of matplotlib may be configured. This control is not limited to configuration files; one may also access an rc
object via the matplotlib API. Each of these is covered in the following few sections.
The configuration of matplotlib is possible through the creation and editing of the matplotlibrc
file. The matplotlib module will search for this file in the following locations:
$HOME/.matplotlib
directoryINSTALL/matplotlib/mpl-data/
, where INSTALL
is the Python site-packages directory where matplotlib was installed$HOME/.matplotlib
is not writableMPLCONFIGDIR
environment variable (if defined, this directory will override the use of $HOME/.matplotlib
)You can use matplotlib to find the location of your configuration directory by using the following code:
In [30]: mpl.get_configdir() Out[30]: '/Users/yourusername/.matplotlib'
Similarly, you can display the currently active matplotlibrc
file with the help of the following code:
In [31]: mpl.matplotlib_fname() Out[31]: '/Users/yourusername/mastering-matplotlib/.venv-mmpl/lib/python3.4/site-packages/matplotlib/mpl-data/matplotlibrc'
There are hundreds of configuration options that are available to you via the matplotlibrc
file:
In [32]: len(mpl.rcParams.keys()) Out[32]: 200
You can have a look at some of these with the following code:
In [33]: dict(list(mpl.rcParams.items())[:10]) Out[33]: {'axes.grid': False, 'mathtext.fontset': 'cm', 'mathtext.cal': 'cursive', 'docstring.hardcopy': False, 'animation.writer': 'ffmpeg', 'animation.mencoder_path': 'mencoder', 'backend.qt5': 'PyQt5', 'keymap.fullscreen': ['f', 'ctrl+f'], 'image.resample': False, 'animation.ffmpeg_path': 'ffmpeg'}
The configuration options that you need depend entirely upon your use cases, and thanks to matplotlib's ability to search multiple locations, you can have a global configuration file as well as per-project configurations.
We've already run into a special case of matplotlib configuration—the contents of the style files that we saw at the beginning of this chapter. If you were so inclined, all of those values could be entered into a matplotlibrc
file, thus setting the default global look and feel for matplotlib.
A complete template for the matplotlbrc
file is available in the matplotlib repository on GitHub. This is the canonical reference for all your matplotlib configuration needs. However, we will point out a few that may be helpful if you keep them in mind, including some that may be used to decrease the render times:
agg.path.chunksize: 20000
: This improves the speed of operations slightly and prevents an Agg
rendering failurepath.simplify: true
: This removes the invisible points to reduce the file size and increase the rendering speedsavefig.jpeg_quality: xx
: This lowers the default .jpg
quality of the saved filesaxes.formatter.limits
: This indicates when you use scientific notations for exponentswebagg.port
: This is the port that you should use for the web server in the WebAgg
backendwebagg.port_retries
: With this, the number of other random ports will be tried until the one that is available is foundIn addition to setting the options in the matplotlibrc
file, you have the ability to change the configuration values on the fly by directly accessing the rcParams
dictionary that we saw earlier:
In [34]: mpl.rcParams['savefig.jpeg_quality'] = 72 Out[34]: mpl.rcParams['axes.formatter.limits'] = [-5, 5]
If you either find out that your changes have caused some problems, or you want to revert to the default values for any reason, you can do so with mpl.rcdefaults()
, which is demonstrated in the following code:
In [35]: mpl.rcParams['axes.formatter.limits'] Out[35]: [-5, 5] In [36]: mpl.rcdefaults() In [37]: mpl.rcParams['axes.formatter.limits'] Out[37]: [-7, 7]
If you are using matplotlib via IPython, as many do, there are IPython matplotlib configuration options that you should be aware of, especially if you regularly use different backends or integrate with different event loops. When you start up IPython, you have the ability to configure matplotlib for interactive use by setting a default matplotlib backend in the following way:
--matplotlib=XXX
In the preceding code, XXX
is one of auto
, gtk
, gtk3
, inline
, nbagg
, osx
, qt
, qt4
, qt5
, tk
, or wx
. Similarly, you can enable a GUI event loop integration with the following option:
--gui=XXX
In the preceding code, XXX
is one of glut
, gtk
, gtk3
, none
, osx
, pyglet
, qt
, qt4
, tk
, or wx
.
While you may see the --pylab
or %pylab
option being referred to in older books and various online resources (including some of matplotlib's own official documentation), its use has been discouraged since IPython version 1.0. It is better to import the modules that you will be using explicitly and not use the deprecated pylab interface at all.