You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
<liclass="toctree-l2"><aclass="reference internal" href="figure/writing_a_backend_pyplot_interface.html">Writing a backend -- the pyplot interface</a></li>
</ul>
</details></li>
</ul>
<ulclass="nav bd-sidenav">
<liclass="toctree-l1 has-children"><aclass="reference internal" href="axes/index.html">Axes and subplots</a><details><summary><spanclass="toctree-toggle" role="presentation"><iclass="fa-solid fa-chevron-down"></i></span></summary><ul>
<liclass="toctree-l2"><aclass="reference internal" href="axes/axes_intro.html">Introduction to Axes (or Subplots)</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="axes/arranging_axes.html">Arranging multiple Axes in a Figure</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="text/pgf.html">Text rendering with XeLaTeX/LuaLaTeX via the <codeclass="docutils literal notranslate"><spanclass="pre">pgf</span></code> backend</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="text/usetex.html">Text rendering with LaTeX</a></li>
</ul>
</details></li>
</ul>
<ulclass="nav bd-sidenav">
<liclass="toctree-l1 has-children"><aclass="reference internal" href="animations/index.html">Animations using Matplotlib</a><details><summary><spanclass="toctree-toggle" role="presentation"><iclass="fa-solid fa-chevron-down"></i></span></summary><ul>
<liclass="toctree-l2"><aclass="reference internal" href="animations/animations.html">Animations using Matplotlib</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="animations/blitting.html">Faster rendering by using blitting</a></li>
<spanid="customizing"></span><spanid="sphx-glr-users-explain-customizing-py"></span><h1>Customizing Matplotlib with style sheets and rcParams<aclass="headerlink" href="#customizing-matplotlib-with-style-sheets-and-rcparams" title="Link to this heading">#</a></h1>
<p>Tips for customizing the properties and default styles of Matplotlib.</p>
<p>There are three ways to customize Matplotlib:</p>
<olclass="arabic simple">
<li><p><aclass="reference internal" href="#customizing-with-dynamic-rc-settings"><spanclass="std std-ref">Setting rcParams at runtime</span></a>.</p></li>
<li><p><aclass="reference internal" href="#customizing-with-matplotlibrc-files"><spanclass="std std-ref">Changing your matplotlibrc file</span></a>.</p></li>
</ol>
<p>Setting rcParams at runtime takes precedence over style sheets, style
sheets take precedence over <codeclass="file docutils literal notranslate"><spanclass="pre">matplotlibrc</span></code> files.</p>
<sectionid="runtime-rc-settings">
<spanid="customizing-with-dynamic-rc-settings"></span><h2>Runtime rc settings<aclass="headerlink" href="#runtime-rc-settings" title="Link to this heading">#</a></h2>
<p>You can dynamically change the default rc (runtime configuration)
settings in a python script or interactively from the python shell. All
rc settings are stored in a dictionary-like variable called
<aclass="reference internal" href="../../api/matplotlib_configuration_api.html#matplotlib.rcParams" title="matplotlib.rcParams"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">matplotlib.rcParams</span></code></a>, which is global to the matplotlib package.
See <aclass="reference internal" href="../../api/matplotlib_configuration_api.html#matplotlib.rcParams" title="matplotlib.rcParams"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.rcParams</span></code></a> for a full list of configurable rcParams.
rcParams can be modified directly, for example:</p>
<imgsrc="../../_images/sphx_glr_customizing_001.png" srcset="../../_images/sphx_glr_customizing_001.png, ../../_images/sphx_glr_customizing_001_2_00x.png 2.00x" alt="customizing" class = "sphx-glr-single-img"/><p>Note, that in order to change the usual <aclass="reference internal" href="../../api/_as_gen/matplotlib.axes.Axes.plot.html#matplotlib.axes.Axes.plot" title="matplotlib.axes.Axes.plot"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">plot</span></code></a> color you have to
change the <em>prop_cycle</em> property of <em>axes</em>:</p>
<ahref="../../api/_as_gen/matplotlib.pyplot.plot.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot" class="sphx-glr-backref-module-matplotlib-pyplot sphx-glr-backref-type-py-function"><spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">plot</span></a><spanclass="p">(</span><ahref="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="numpy.ndarray" class="sphx-glr-backref-module-numpy sphx-glr-backref-type-py-class sphx-glr-backref-instance"><spanclass="n">data</span></a><spanclass="p">)</span><spanclass="c1"># first color is red</span>
</pre></div>
</div>
<imgsrc="../../_images/sphx_glr_customizing_002.png" srcset="../../_images/sphx_glr_customizing_002.png, ../../_images/sphx_glr_customizing_002_2_00x.png 2.00x" alt="customizing" class = "sphx-glr-single-img"/><p>Matplotlib also provides a couple of convenience functions for modifying rc
settings. <aclass="reference internal" href="../../api/matplotlib_configuration_api.html#matplotlib.rc" title="matplotlib.rc"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.rc</span></code></a> can be used to modify multiple
settings in a single group at once, using keyword arguments:</p>
<imgsrc="../../_images/sphx_glr_customizing_003.png" srcset="../../_images/sphx_glr_customizing_003.png, ../../_images/sphx_glr_customizing_003_2_00x.png 2.00x" alt="customizing" class = "sphx-glr-single-img"/><sectionid="temporary-rc-settings">
<h3>Temporary rc settings<aclass="headerlink" href="#temporary-rc-settings" title="Link to this heading">#</a></h3>
<p>The <aclass="reference internal" href="../../api/matplotlib_configuration_api.html#matplotlib.rcParams" title="matplotlib.rcParams"><codeclass="xref py py-data docutils literal notranslate"><spanclass="pre">matplotlib.rcParams</span></code></a> object can also be changed temporarily using
<imgsrc="../../_images/sphx_glr_customizing_004.png" srcset="../../_images/sphx_glr_customizing_004.png, ../../_images/sphx_glr_customizing_004_2_00x.png 2.00x" alt="customizing" class = "sphx-glr-single-img"/><p><aclass="reference internal" href="../../api/matplotlib_configuration_api.html#matplotlib.rc_context" title="matplotlib.rc_context"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.rc_context</span></code></a> can also be used as a decorator to modify the
<spanid="customizing-with-style-sheets"></span><h2>Using style sheets<aclass="headerlink" href="#using-style-sheets" title="Link to this heading">#</a></h2>
<p>Another way to change the visual appearance of plots is to set the
rcParams in a so-called style sheet and import that style sheet with
<aclass="reference internal" href="../../api/style_api.html#matplotlib.style.use" title="matplotlib.style.use"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.style.use</span></code></a>. In this way you can switch easily between
different styles by simply changing the imported style sheet. A style
sheets looks the same as a <aclass="reference internal" href="#matplotlibrc-sample"><spanclass="std std-ref">matplotlibrc</span></a>
file, but in a style sheet you can only set rcParams that are related
to the actual style of a plot. Other rcParams, like <em>backend</em>, will be
ignored. <codeclass="file docutils literal notranslate"><spanclass="pre">matplotlibrc</span></code> files support all rcParams. The
rationale behind this is to make style sheets portable between
different machines without having to worry about dependencies which
might or might not be installed on another machine. For a full list of
rcParams see <aclass="reference internal" href="../../api/matplotlib_configuration_api.html#matplotlib.rcParams" title="matplotlib.rcParams"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.rcParams</span></code></a>. For a list of rcParams that are
ignored in style sheets see <aclass="reference internal" href="../../api/style_api.html#matplotlib.style.use" title="matplotlib.style.use"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.style.use</span></code></a>.</p>
<p>There are a number of pre-defined styles <aclass="reference internal" href="../../gallery/style_sheets/style_sheets_reference.html"><spanclass="doc">provided by Matplotlib</span></a>. For
example, there's a pre-defined style called "ggplot", which emulates the
aesthetics of <aclass="reference external" href="https://ggplot2.tidyverse.org/">ggplot</a> (a popular plotting package for <aclass="reference external" href="https://www.r-project.org/">R</a>). To use this
<h3>Defining your own style<aclass="headerlink" href="#defining-your-own-style" title="Link to this heading">#</a></h3>
<p>You can create custom styles and use them by calling <aclass="reference internal" href="../../api/style_api.html#matplotlib.style.use" title="matplotlib.style.use"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">style.use</span></code></a> with
the path or URL to the style sheet.</p>
<p>For example, you might want to create
<codeclass="docutils literal notranslate"><spanclass="pre">./images/presentation.mplstyle</span></code> with the following:</p>
<h3>Distributing styles<aclass="headerlink" href="#distributing-styles" title="Link to this heading">#</a></h3>
<p>You can include style sheets into standard importable Python packages (which
can be e.g. distributed on PyPI). If your package is importable as
<codeclass="docutils literal notranslate"><spanclass="pre">import</span><spanclass="pre">mypackage</span></code>, with a <codeclass="docutils literal notranslate"><spanclass="pre">mypackage/__init__.py</span></code> module, and you add
a <codeclass="docutils literal notranslate"><spanclass="pre">mypackage/presentation.mplstyle</span></code> style sheet, then it can be used as
<codeclass="docutils literal notranslate"><spanclass="pre">dotted.package.name</span></code>) are also supported.</p>
<p>Alternatively, you can make your style known to Matplotlib by placing
your <codeclass="docutils literal notranslate"><spanclass="pre"><style-name>.mplstyle</span></code> file into <codeclass="docutils literal notranslate"><spanclass="pre">mpl_configdir/stylelib</span></code>. You
can then load your custom style sheet with a call to
<codeclass="docutils literal notranslate"><spanclass="pre">style.use(<style-name>)</span></code>. By default <codeclass="docutils literal notranslate"><spanclass="pre">mpl_configdir</span></code> should be
<codeclass="docutils literal notranslate"><spanclass="pre">~/.config/matplotlib</span></code>, but you can check where yours is with
<aclass="reference internal" href="../../api/matplotlib_configuration_api.html#matplotlib.get_configdir" title="matplotlib.get_configdir"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.get_configdir()</span></code></a>; you may need to create this directory. You
also can change the directory where Matplotlib looks for the stylelib/
folder by setting the <spanclass="target" id="index-0"></span><aclass="reference internal" href="../../install/environment_variables_faq.html#envvar-MPLCONFIGDIR"><codeclass="xref std std-envvar docutils literal notranslate"><spanclass="pre">MPLCONFIGDIR</span></code></a> environment variable, see
<aclass="reference internal" href="../../install/index.html#locating-matplotlib-config-dir"><spanclass="std std-ref">matplotlib configuration and cache directory locations</span></a>.</p>
<p>Note that a custom style sheet in <codeclass="docutils literal notranslate"><spanclass="pre">mpl_configdir/stylelib</span></code> will override a
style sheet defined by Matplotlib if the styles have the same name.</p>
<p>Once your <codeclass="docutils literal notranslate"><spanclass="pre"><style-name>.mplstyle</span></code> file is in the appropriate
<codeclass="docutils literal notranslate"><spanclass="pre">mpl_configdir</span></code> you can specify your style with:</p>
<codeclass="file docutils literal notranslate"><spanclass="pre">$XDG_CONFIG_HOME/matplotlib/matplotlibrc</span></code>) if you've customized
your environment.</p></li>
<li><p>On other platforms, it looks in <codeclass="file docutils literal notranslate"><spanclass="pre">.matplotlib/matplotlibrc</span></code>.</p></li>
</ul>
<p>See <aclass="reference internal" href="../../install/index.html#locating-matplotlib-config-dir"><spanclass="std std-ref">matplotlib configuration and cache directory locations</span></a>.</p>
</li>
<li><p><codeclass="file docutils literal notranslate"><em><spanclass="pre">INSTALL</span></em><spanclass="pre">/matplotlib/mpl-data/matplotlibrc</span></code>, where
<codeclass="file docutils literal notranslate"><em><spanclass="pre">INSTALL</span></em></code> is something like
<codeclass="file docutils literal notranslate"><spanclass="pre">/usr/lib/python3.10/site-packages</span></code> on Linux, and maybe
<codeclass="file docutils literal notranslate"><spanclass="pre">C:\Python310\Lib\site-packages</span></code> 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
user-specific matplotlib directory.</p></li>
</ol>
<p>Once a <codeclass="file docutils literal notranslate"><spanclass="pre">matplotlibrc</span></code> file has been found, it will <em>not</em> search
any of the other paths. When a
<aclass="reference internal" href="#customizing-with-style-sheets"><spanclass="std std-ref">style sheet</span></a> is given with
<codeclass="docutils literal notranslate"><spanclass="pre">style.use('<path>/<style-name>.mplstyle')</span></code>, settings specified in
the style sheet take precedence over settings in the
<p>See below for a sample <aclass="reference internal" href="#matplotlibrc-sample"><spanclass="std std-ref">matplotlibrc file</span></a>
and see <aclass="reference internal" href="../../api/matplotlib_configuration_api.html#matplotlib.rcParams" title="matplotlib.rcParams"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.rcParams</span></code></a> for a full list of configurable rcParams.</p>
<sectionid="the-default-matplotlibrc-file">
<spanid="matplotlibrc-sample"></span><h3>The default <codeclass="file docutils literal notranslate"><spanclass="pre">matplotlibrc</span></code> file<aclass="headerlink" href="#the-default-matplotlibrc-file" title="Link to this heading">#</a></h3>