<liclass="toctree-l2"><aclass="reference internal" href="../users/explain/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="../users/explain/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="../users/explain/axes/axes_intro.html">Introduction to Axes (or Subplots)</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="../users/explain/axes/arranging_axes.html">Arranging multiple Axes in a Figure</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="../users/explain/artists/imshow_extent.html">Understanding the extent keyword argument of imshow</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../users/explain/customizing.html">Customizing Matplotlib with style sheets and rcParams</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="../users/explain/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="../users/explain/text/text_intro.html">Text in Matplotlib</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="../users/explain/text/text_props.html">Text properties and layout</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="../users/explain/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="../users/explain/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="../users/explain/animations/animations.html">Animations using Matplotlib</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="../users/explain/animations/blitting.html">Faster rendering by using blitting</a></li>
<liclass="toctree-l1 current active has-children"><aclass="current reference internal" href="#">Installation</a><detailsopen="open"><summary><spanclass="toctree-toggle" role="presentation"><iclass="fa-solid fa-chevron-down"></i></span></summary><ul>
<p>uv usually installs its own versions of Python from the
python-build-standalone project, and only recent versions of those
Python builds (August 2025) work properly with the <codeclass="docutils literal notranslate"><spanclass="pre">tkagg</span></code> backend
for displaying plots in a window. Please make sure you are using uv
0.8.7 or newer (update with e.g. <codeclass="docutils literal notranslate"><spanclass="pre">uv</span><spanclass="pre">self</span><spanclass="pre">update</span></code>) and that your
bundled Python installs are up to date (with <codeclass="docutils literal notranslate"><spanclass="pre">uv</span><spanclass="pre">python</span><spanclass="pre">upgrade</span>
<spanclass="pre">--reinstall</span></code>). Alternatively, you can use one of the other
<p><aclass="reference internal" href="#install-nightly-build"><spanclass="std std-ref">Install a nightly build</span></a></p>
<p><aclass="reference internal" href="#install-source"><spanclass="std std-ref">Install from source</span></a></p>
</div>
</div>
<sectionid="install-an-official-release">
<spanid="install-official"></span><h2>Install an official release<aclass="headerlink" href="#install-an-official-release" title="Link to this heading">#</a></h2>
<p>Matplotlib releases are available as wheel packages for macOS, Windows and
Linux on <aclass="reference external" href="https://pypi.org/project/matplotlib/">PyPI</a>. Install it using
<p>If this command results in Matplotlib being compiled from source and
there's trouble with the compilation, you can add <codeclass="docutils literal notranslate"><spanclass="pre">--prefer-binary</span></code> to
select the newest version of Matplotlib for which there is a
precompiled wheel for your OS and Python.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>The following non-interactive backends work out of the box: Agg,
ps, pdf, svg</p>
<p>The TkAgg interactive backend also typically works out of the box.
It requires Tk bindings, which are usually provided via the Python
standard library's <codeclass="docutils literal notranslate"><spanclass="pre">tkinter</span></code> module. On some OSes, you may need
to install a separate package like <codeclass="docutils literal notranslate"><spanclass="pre">python3-tk</span></code> to add this
component of the standard library.</p>
<p>Some tools like <codeclass="docutils literal notranslate"><spanclass="pre">uv</span></code> make use of Python builds from the
python-build-standalone project, which only gained usable Tk
bindings recently (August 2025). If you are having trouble with the
TkAgg backend, ensure you have an up-to-date build, e.g. <codeclass="docutils literal notranslate"><spanclass="pre">uv</span><spanclass="pre">self</span>
<spanid="install-third-party"></span><h2>Third-party distributions<aclass="headerlink" href="#third-party-distributions" title="Link to this heading">#</a></h2>
<p>Various third-parties provide Matplotlib for their environments.</p>
<sectionid="conda-packages">
<h3>Conda packages<aclass="headerlink" href="#conda-packages" title="Link to this heading">#</a></h3>
<p>Matplotlib is available both via the <em>anaconda main channel</em></p>
<spanid="install-nightly-build"></span><h2>Install a nightly build<aclass="headerlink" href="#install-a-nightly-build" title="Link to this heading">#</a></h2>
<p>Matplotlib makes nightly development build wheels available on the
<h2>Configure build and behavior defaults<aclass="headerlink" href="#configure-build-and-behavior-defaults" title="Link to this heading">#</a></h2>
<p>We provide a <aclass="reference external" href="https://github.com/matplotlib/matplotlib/blob/main/meson.options">meson.options</a> file containing options with which you can use to
customize the build process. For example, which default backend to use, whether some of
the optional libraries that Matplotlib ships with are installed, and so on. These
options will be particularly useful to those packaging Matplotlib.</p>
<p>Aspects of some behavioral defaults of the library can be configured via:</p>
<liclass="toctree-l2"><aclass="reference internal" href="environment_variables_faq.html#setting-environment-variables-in-linux-and-macos">Setting environment variables in Linux and macOS</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="environment_variables_faq.html#setting-environment-variables-in-windows">Setting environment variables in Windows</a></li>
</ul>
</li>
</ul>
</div>
<p>Default plotting appearance and behavior can be configured via the
<h2>Dependencies<aclass="headerlink" href="#dependencies" title="Link to this heading">#</a></h2>
<p>Mandatory dependencies should be installed automatically if you install Matplotlib using
a package manager such as <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">conda</span></code>; therefore this list is primarily for
<spanid="installing-faq"></span><h2>Frequently asked questions<aclass="headerlink" href="#frequently-asked-questions" title="Link to this heading">#</a></h2>
<sectionid="report-a-compilation-problem">
<h3>Report a compilation problem<aclass="headerlink" href="#report-a-compilation-problem" title="Link to this heading">#</a></h3>
<h3>Matplotlib compiled fine, but nothing shows up when I use it<aclass="headerlink" href="#matplotlib-compiled-fine-but-nothing-shows-up-when-i-use-it" title="Link to this heading">#</a></h3>
<p>The first thing to try is a <aclass="reference internal" href="#clean-install"><spanclass="std std-ref">clean install</span></a> and see if
that helps. If not, the best way to test your install is by running a script,
rather than working interactively from a python shell or an integrated
development environment such as <strongclass="program">IDLE</strong> which add additional
complexities. Open up a UNIX shell or a DOS command prompt and run, for
<p>This will give you additional information about which backends Matplotlib is
loading, version information, and more. At this point you might want to make
sure you understand Matplotlib's <aclass="reference internal" href="../users/explain/customizing.html#customizing"><spanclass="std std-ref">configuration</span></a>
process, governed by the <codeclass="file docutils literal notranslate"><spanclass="pre">matplotlibrc</span></code> configuration file which contains
instructions within and the concept of the Matplotlib backend.</p>
<p>If you are still having trouble, see <aclass="reference internal" href="../users/faq.html#reporting-problems"><spanclass="std std-ref">Get help</span></a>.</p>
</section>
<sectionid="how-to-completely-remove-matplotlib">
<spanid="clean-install"></span><h3>How to completely remove Matplotlib<aclass="headerlink" href="#how-to-completely-remove-matplotlib" title="Link to this heading">#</a></h3>
<p>Occasionally, problems with Matplotlib can be solved with a clean
installation of the package. In order to fully remove an installed Matplotlib:</p>
<olclass="arabic simple">
<li><p>Delete the caches from your <aclass="reference internal" href="#locating-matplotlib-config-dir"><spanclass="std std-ref">Matplotlib configuration directory</span></a>.</p></li>
<li><p>Delete any Matplotlib directories or eggs from your <aclass="reference internal" href="#locating-matplotlib-install"><spanclass="std std-ref">installation
directory</span></a>.</p></li>
</ol>
</section>
<sectionid="macos-notes">
<h3>macOS Notes<aclass="headerlink" href="#macos-notes" title="Link to this heading">#</a></h3>
<sectionid="which-python-for-macos">
<spanid="id1"></span><h4>Which python for macOS?<aclass="headerlink" href="#which-python-for-macos" title="Link to this heading">#</a></h4>
<p>Apple ships macOS with its own Python, in <codeclass="docutils literal notranslate"><spanclass="pre">/usr/bin/python</span></code>, and its own copy
of Matplotlib. Unfortunately, the way Apple currently installs its own copies
of NumPy, Scipy and Matplotlib means that these packages are difficult to
upgrade (see <aclass="reference external" href="https://github.com/MacPython/wiki/wiki/Which-Python#system-python-and-extra-python-packages">system python packages</a>). For that reason we strongly suggest
that you install a fresh version of Python and use that as the basis for
installing libraries such as NumPy and Matplotlib. One convenient way to
install Matplotlib with other useful Python software is to use the <aclass="reference external" href="https://www.anaconda.com/">Anaconda</a>
Python scientific software collection, which includes Python itself and a
wide range of libraries; if you need a library that is not available from the
collection, you can install it yourself using standard methods such as <em>pip</em>.
See the Anaconda web page for installation support.</p>
<p>Other options for a fresh Python install are the standard installer from
<aclass="reference external" href="https://www.python.org/downloads/macos/">python.org</a>, or installing
Python using a general macOS package management system such as <aclass="reference external" href="https://brew.sh/">homebrew</a> or <aclass="reference external" href="https://www.macports.org">macports</a>. Power users on
macOS will likely want one of homebrew or macports on their system to install
open source software packages, but it is perfectly possible to use these
systems with another source for your Python binary, such as Anaconda
or Python.org Python.</p>
</section>
<sectionid="installing-macos-binary-wheels">
<spanid="install-macos-binaries"></span><h4>Installing macOS binary wheels<aclass="headerlink" href="#installing-macos-binary-wheels" title="Link to this heading">#</a></h4>
<p>If you are using Python from <aclass="reference external" href="https://www.python.org">https://www.python.org</a>, Homebrew, or Macports,
then you can use the standard pip installer to install Matplotlib binaries in
the form of wheels.</p>
<p>pip is installed by default with python.org and Homebrew Python, but needs to
<p>You might also want to install IPython or the Jupyter notebook (<codeclass="docutils literal notranslate"><spanclass="pre">python3</span><spanclass="pre">-m</span><spanclass="pre">pip</span>
<p>If you get a result like <codeclass="docutils literal notranslate"><spanclass="pre">/usr/bin/python...</span></code>, then you are getting the
Python installed with macOS, which is probably not what you want. Try closing
and restarting Terminal.app before running the check again. If that doesn't fix
the problem, depending on which Python you wanted to use, consider reinstalling
Python.org Python, or check your homebrew or macports setup. Remember that
the disk image installer only works for Python.org Python, and will not get
picked up by other Pythons. If all these fail, please <aclass="reference internal" href="../users/faq.html#reporting-problems"><spanclass="std std-ref">let us know</span></a>.</p>
</section>
</section>
</section>
<sectionid="troubleshooting">
<spanid="troubleshooting-install"></span><h2>Troubleshooting<aclass="headerlink" href="#troubleshooting" title="Link to this heading">#</a></h2>
<sectionid="obtaining-matplotlib-version">
<spanid="matplotlib-version"></span><h3>Obtaining Matplotlib version<aclass="headerlink" href="#obtaining-matplotlib-version" title="Link to this heading">#</a></h3>
<p>To find out your Matplotlib version number, import it and print the
<spanid="locating-matplotlib-config-dir"></span><h3><codeclass="file docutils literal notranslate"><spanclass="pre">matplotlib</span></code> configuration and cache directory locations<aclass="headerlink" href="#matplotlib-configuration-and-cache-directory-locations" title="Link to this heading">#</a></h3>
<p>Each user has a Matplotlib configuration directory which may contain a
<aclass="reference internal" href="../users/explain/customizing.html#customizing-with-matplotlibrc-files"><spanclass="std std-ref">matplotlibrc</span></a> file. To
locate your <codeclass="file docutils literal notranslate"><spanclass="pre">matplotlib/</span></code> configuration directory, use
<p>On Windows, both the config directory and the cache directory are
the same and are in your <codeclass="file docutils literal notranslate"><spanclass="pre">Documents</span><spanclass="pre">and</span><spanclass="pre">Settings</span></code> or <codeclass="file docutils literal notranslate"><spanclass="pre">Users</span></code>
<spanclass="go">'C:\\Documents and Settings\\jdhunter\\.matplotlib'</span>
</pre></div>
</div>
<p>If you would like to use a different configuration directory, you can
do so by specifying the location in your <spanclass="target" id="index-1"></span><aclass="reference internal" href="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="environment_variables_faq.html#setting-linux-macos-environment-variables"><spanclass="std std-ref">Setting environment variables in Linux and macOS</span></a>. Note that
<spanclass="target" id="index-2"></span><aclass="reference internal" href="environment_variables_faq.html#envvar-MPLCONFIGDIR"><codeclass="xref std std-envvar docutils literal notranslate"><spanclass="pre">MPLCONFIGDIR</span></code></a> sets the location of both the configuration
<liclass="toc-h3 nav-item toc-entry"><aclass="reference internal nav-link" href="#report-a-compilation-problem">Report a compilation problem</a></li>
<liclass="toc-h3 nav-item toc-entry"><aclass="reference internal nav-link" href="#matplotlib-compiled-fine-but-nothing-shows-up-when-i-use-it">Matplotlib compiled fine, but nothing shows up when I use it</a></li>
<liclass="toc-h3 nav-item toc-entry"><aclass="reference internal nav-link" href="#how-to-completely-remove-matplotlib">How to completely remove Matplotlib</a></li>