<h1><aclass="toc-backref" href="#id7">Installation Guide</a><aclass="headerlink" href="#installation-guide" title="Permalink to this headline">¶</a></h1>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">If you wish to contribute to the project, it's recommended you
<aclass="reference internal" href="#install-from-source"><spanclass="std std-ref">install the latest development version</span></a>.</p>
<h2><aclass="toc-backref" href="#id8">Installing an official release</a><aclass="headerlink" href="#installing-an-official-release" title="Permalink to this headline">¶</a></h2>
<p>Matplotlib and its dependencies are available as wheel packages for macOS,
<p>Although not required, we suggest also installing <codeclass="docutils literal notranslate"><spanclass="pre">IPython</span></code> for
interactive use. To easily install a complete Scientific Python
stack, see <aclass="reference internal" href="#install-scipy-dists"><spanclass="std std-ref">Scientific Python Distributions</span></a> below.</p>
<divclass="section" id="test-data">
<h3><aclass="toc-backref" href="#id9">Test data</a><aclass="headerlink" href="#test-data" title="Permalink to this headline">¶</a></h3>
<p>The wheels (<codeclass="file docutils literal notranslate"><spanclass="pre">*.whl</span></code>) on the <aclass="reference external" href="https://pypi.org/project/matplotlib/">PyPI download page</a> do not contain test data
or example code.</p>
<p>If you want to try the many demos that come in the Matplotlib source
distribution, download the <codeclass="file docutils literal notranslate"><spanclass="pre">*.tar.gz</span></code> file and look in the
<h2><aclass="toc-backref" href="#id10">Third-party distributions of Matplotlib</a><aclass="headerlink" href="#third-party-distributions-of-matplotlib" title="Permalink to this headline">¶</a></h2>
<spanid="install-scipy-dists"></span><h3><aclass="toc-backref" href="#id11">Scientific Python Distributions</a><aclass="headerlink" href="#scientific-python-distributions" title="Permalink to this headline">¶</a></h3>
<p><aclass="reference external" href="https://www.anaconda.com/">Anaconda</a> and <aclass="reference external" href="https://www.activestate.com/activepython/downloads">ActiveState</a> are excellent
choices that "just work" out of the box for Windows, macOS and common
Linux platforms. <aclass="reference external" href="https://winpython.github.io/">WinPython</a> is an
option for Windows users. All of these distributions include
Matplotlib and <em>lots</em> of other useful (data) science tools.</p>
<h3><aclass="toc-backref" href="#id12">Linux: using your package manager</a><aclass="headerlink" href="#linux-using-your-package-manager" title="Permalink to this headline">¶</a></h3>
<p>If you are on Linux, you might prefer to use your package manager. Matplotlib
is packaged for almost every major Linux distribution.</p>
<spanid="install-from-source"></span><h2><aclass="toc-backref" href="#id13">Installing from source</a><aclass="headerlink" href="#installing-from-source" title="Permalink to this headline">¶</a></h2>
<p>If you are interested in contributing to Matplotlib development,
running the latest source code, or just like to build everything
yourself, it is not difficult to build Matplotlib from source. Grab
the latest <em>tar.gz</em> release file from <aclass="reference external" href="https://pypi.org/project/matplotlib/">the PyPI files page</a>, or if you want to
develop Matplotlib or just need the latest bugfixed version, grab the
latest git version, and see <aclass="reference internal" href="../faq/installing_faq.html#install-from-git"><spanclass="std std-ref">Install from source</span></a>.</p>
<p>Matplotlib can be installed from the source directory with a simple</p>
<p>We provide a <aclass="reference external" href="https://raw.githubusercontent.com/matplotlib/matplotlib/master/setup.cfg.template">setup.cfg</a> file 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. This
file will be particularly useful to those packaging Matplotlib.</p>
<divclass="section" id="dependencies">
<spanid="install-requirements"></span><h3><aclass="toc-backref" href="#id14">Dependencies</a><aclass="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h3>
<p>Matplotlib requires the following dependencies:</p>
<p>Optionally, you can also install a number of packages to enable better user
interface toolkits. See <aclass="reference internal" href="../tutorials/introductory/usage.html#what-is-a-backend"><spanclass="std std-ref">What is a backend?</span></a> for more details on the
optional Matplotlib backends and the capabilities they provide.</p>
<ulclass="simple">
<li><aclass="reference external" href="https://docs.python.org/3/library/tk.html">Tk</a> (>= 8.3, != 8.6.0 or 8.6.1): for the Tk-based backends.</li>
<li><aclass="reference external" href="https://pypi.org/project/PyQt4">PyQt4</a> (>= 4.6) or <aclass="reference external" href="https://pypi.org/project/PySide">PySide</a> (>= 1.0.3) <aclass="footnote-reference" href="#id4" id="id1">[1]</a>: for the Qt4-based backends.</li>
<li><aclass="reference external" href="https://pypi.org/project/PyQt5">PyQt5</a> or <aclass="reference external" href="https://pypi.org/project/PySide2">PySide2</a>: for the Qt5-based backends.</li>
<li><aclass="reference external" href="https://pygobject.readthedocs.io/en/latest/">PyGObject</a>: for the GTK3-based backends <aclass="footnote-reference" href="#id5" id="id2">[2]</a>.</li>
<li><aclass="reference external" href="https://www.wxpython.org/">wxPython</a> (>= 4) <aclass="footnote-reference" href="#id6" id="id3">[3]</a>: for the wx-based backends.</li>
<li><aclass="reference external" href="https://pycairo.readthedocs.io/en/latest/">pycairo</a> (>= 1.11.0) or <aclass="reference external" href="https://cairocffi.readthedocs.io/en/latest/">cairocffi</a> (>= 0.8): for the GTK3 and/or cairo-based
backends.</li>
<li><aclass="reference external" href="https://pypi.org/project/tornado">Tornado</a>: for the WebAgg backend.</li>
<tr><tdclass="label"><aclass="fn-backref" href="#id3">[3]</a></td><td>If using pip (and not conda) on Linux, wxPython wheels must be manually
downloaded from <aclass="reference external" href="https://wxpython.org/pages/downloads/">https://wxpython.org/pages/downloads/</a>.</td></tr>
</tbody>
</table>
<p>For better support of animation output format and image file formats, LaTeX,
etc., you can install the following:</p>
<ulclass="simple">
<li><aclass="reference external" href="https://www.ffmpeg.org/">ffmpeg</a>: for saving movies.</li>
<li><aclass="reference external" href="https://www.imagemagick.org/script/index.php">ImageMagick</a>: for saving
animated gifs.</li>
<li><aclass="reference external" href="https://www.latex-project.org/">LaTeX</a> (with <aclass="reference external" href="https://ctan.org/pkg/cm-super">cm-super</a> ) and <aclass="reference external" href="https://ghostscript.com/download/">GhostScript (>=9.0)</a> : for rendering text with
LaTeX.</li>
<li><aclass="reference external" href="https://www.fontconfig.org">fontconfig</a> (>= 2.7): for detection of system
fonts on Linux.</li>
</ul>
</div>
<divclass="section" id="freetype-and-qhull">
<h3><aclass="toc-backref" href="#id15">FreeType and Qhull</a><aclass="headerlink" href="#freetype-and-qhull" title="Permalink to this headline">¶</a></h3>
<p>Matplotlib depends on <aclass="reference external" href="https://www.freetype.org/">FreeType</a> (>=
2.3), a font rendering library, and on <aclass="reference external" href="http://www.qhull.org/">Qhull</a> (>= 2015.2), a library for computing
triangulations. By default (except on AIX) Matplotlib downloads and
builds its own copy of FreeType (this is necessary to run the test
suite, because different versions of FreeType rasterize characters
differently), and uses its own copy of Qhull.</p>
<p>To force Matplotlib to use a copy of FreeType or Qhull already installed in
your system, create a <codeclass="file docutils literal notranslate"><spanclass="pre">setup.cfg</span></code> file with the following contents:</p>
brew install freetype <spanclass="c1"># macOS with Homebrew</span>
conda install freetype <spanclass="c1"># conda, any OS</span>
</pre></div>
</div>
<p>(adapt accordingly for Qhull).</p>
<p>On Linux and macOS, it is also recommended to install <aclass="reference external" href="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</a>, a helper
tool for locating FreeType:</p>
<divclass="highlight-sh notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Pick ONE of the following:</span>
<p>Matplotlib always uses its own copies of the following libraries:</p>
<ulclass="last simple">
<li><codeclass="docutils literal notranslate"><spanclass="pre">Agg</span></code>: the Anti-Grain Geometry C++ rendering engine;</li>
<li><codeclass="docutils literal notranslate"><spanclass="pre">ttconv</span></code>: a TrueType font utility.</li>
</ul>
</div>
</div>
<divclass="section" id="building-on-windows">
<h3><aclass="toc-backref" href="#id16">Building on Windows</a><aclass="headerlink" href="#building-on-windows" title="Permalink to this headline">¶</a></h3>
<p>Compiling Matplotlib (or any other extension module, for that matter) requires
Visual Studio 2015 or later.</p>
<p>If you are building your own Matplotlib wheels (or sdists), note that any DLLs
that you copy into the source tree will be packaged too.</p>
</div>
<divclass="section" id="conda-packages">
<h3><aclass="toc-backref" href="#id17">Conda packages</a><aclass="headerlink" href="#conda-packages" title="Permalink to this headline">¶</a></h3>
<p>The conda packaging scripts for Matplotlib are available at