<divid="unreleased-message"> You are reading an old version of the documentation (v1.5.1). For the latest version see <ahref="https://matplotlib.org/stable/faq/installing_faq.html">https://matplotlib.org/stable/faq/installing_faq.html</a></div>
<li><aclass="reference internal" href="#report-a-compilation-problem">Report a compilation problem</a></li>
<li><aclass="reference internal" 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>
<li><aclass="reference internal" href="#how-to-completely-remove-matplotlib">How to completely remove matplotlib</a><ul>
<li><aclass="reference internal" href="#report-a-compilation-problem" id="id4">Report a compilation problem</a></li>
<li><aclass="reference internal" href="#matplotlib-compiled-fine-but-nothing-shows-up-when-i-use-it" id="id5">matplotlib compiled fine, but nothing shows up when I use it</a></li>
<li><aclass="reference internal" href="#how-to-completely-remove-matplotlib" id="id6">How to completely remove matplotlib</a><ul>
<h2>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="Permalink to this headline">¶</a></h2>
<p>The first thing to try is a <aclass="reference internal" href="#clean-install"><span>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 cd into a
directory containing a minimal example in a file. Something like
<codeclass="file docutils literal"><spanclass="pre">simple_plot.py</span></code> for example:</p>
<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/customizing.html#customizing-matplotlib"><span>configuration</span></a>
process, governed by the <codeclass="file docutils literal"><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="troubleshooting_faq.html#reporting-problems"><span>Getting help</span></a>.</p>
<spanid="clean-install"></span><h2>How to completely remove matplotlib<aclass="headerlink" href="#how-to-completely-remove-matplotlib" title="Permalink to this headline">¶</a></h2>
<p>Occasionally, problems with matplotlib can be solved with a clean
installation of the package.</p>
<p>The process for removing an installation of matplotlib depends on how
matplotlib was originally installed on your system. Follow the steps
below that goes with your original installation method to cleanly
remove matplotlib from your system.</p>
<divclass="section" id="easy-install">
<h3>Easy Install<aclass="headerlink" href="#easy-install" title="Permalink to this headline">¶</a></h3>
<olclass="arabic">
<li><pclass="first">Delete the caches from your <aclass="reference internal" href="troubleshooting_faq.html#locating-matplotlib-config-dir"><span>.matplotlib configuration directory</span></a>.</p>
<li><pclass="first">Delete any .egg files or directories from your <aclass="reference internal" href="troubleshooting_faq.html#locating-matplotlib-install"><span>installation
directory</span></a>.</p>
</li>
</ol>
</div>
<divclass="section" id="windows-installer">
<h3>Windows installer<aclass="headerlink" href="#windows-installer" title="Permalink to this headline">¶</a></h3>
<olclass="arabic simple">
<li>Delete the caches from your <aclass="reference internal" href="troubleshooting_faq.html#locating-matplotlib-config-dir"><span>.matplotlib configuration directory</span></a>.</li>
<li>Use <spanclass="menuselection">Start ‣ Control Panel</span> to start the <strongclass="program">Add and
Remove Software</strong> utility.</li>
</ol>
</div>
<divclass="section" id="source-install">
<h3>Source install<aclass="headerlink" href="#source-install" title="Permalink to this headline">¶</a></h3>
<p>does not properly clean the build directory, and does nothing to the
install directory. To cleanly rebuild:</p>
<olclass="arabic simple">
<li>Delete the caches from your <aclass="reference internal" href="troubleshooting_faq.html#locating-matplotlib-config-dir"><span>.matplotlib configuration directory</span></a>.</li>
<li>Delete the <codeclass="docutils literal"><spanclass="pre">build</span></code> directory in the source tree.</li>
<li>Delete any matplotlib directories or eggs from your <aclass="reference internal" href="troubleshooting_faq.html#locating-matplotlib-install"><span>installation
directory</span></a>.</li>
</ol>
</div>
</div>
<divclass="section" id="how-to-install">
<h2>How to Install<aclass="headerlink" href="#how-to-install" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="source-install-from-git">
<spanid="install-from-git"></span><h3>Source install from git<aclass="headerlink" href="#source-install-from-git" title="Permalink to this headline">¶</a></h3>
<p>This creates links in the right places and installs the command
line script to the appropriate places.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<p>Mac OSX users please see the <aclass="reference internal" href="../users/installing.html#build-osx"><span>Building on OSX</span></a> guide.</p>
<pclass="last">Windows users please see the <aclass="reference internal" href="../users/installing.html#build-windows"><span>Building on Windows</span></a> guide.</p>
</div>
<p>Then, if you want to update your matplotlib at any time, just do:</p>
<p>When you run <codeclass="xref py py-obj docutils literal"><spanclass="pre">git</span><spanclass="pre">pull</span></code>, if the output shows that only Python files have been
updated, you are all set. If C files have changed, you need to run the <codeclass="xref py py-obj docutils literal"><spanclass="pre">python</span>
<spanclass="pre">setup.py</span><spanclass="pre">develop</span></code> command again to compile them.</p>
<p>There is more information on <aclass="reference internal" href="../devel/gitwash/index.html#using-git"><span>using git</span></a> in
the developer docs.</p>
</div>
</div>
<divclass="section" id="linux-notes">
<h2>Linux Notes<aclass="headerlink" href="#linux-notes" title="Permalink to this headline">¶</a></h2>
<p>Because most Linux distributions use some sort of package manager,
we do not provide a pre-built binary for the Linux platform.
Instead, we recommend that you use the “Add Software” method for
your system to install matplotlib. This will guarantee that everything
that is needed for matplotlib will be installed as well.</p>
<p>If, for some reason, you can not use the package manager, Linux usually
comes with at least a basic build system. Follow the <aclass="reference internal" href="#install-from-git"><span>instructions</span></a> found above for how to build and install matplotlib.</p>
</div>
<divclass="section" id="os-x-notes">
<h2>OS-X Notes<aclass="headerlink" href="#os-x-notes" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="which-python-for-os-x">
<spanid="which-python-for-osx"></span><h3>Which python for OS X?<aclass="headerlink" href="#which-python-for-os-x" title="Permalink to this headline">¶</a></h3>
<p>Apple ships OS X with its own Python, in <codeclass="docutils literal"><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 one of the
excellent Python scientific software collections that are now available:</p>
<ulclass="simple">
<li><aclass="reference external" href="https://store.continuum.io/cshop/anaconda/">Anaconda</a> from <aclass="reference external" href="http://continuum.io">Continuum Analytics</a></li>
<li><aclass="reference external" href="https://enthought.com/products/canopy/">Canopy</a> from <aclass="reference external" href="http://enthought.com">Enthought</a></li>
</ul>
<p>These collections include 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>. Continuum and Enthought offer
their own installation support for these collections; see the Ananconda and
Canopy web pages for more information.</p>
<p>Other options for a fresh Python install are the standard installer from
<aclass="reference external" href="https://www.python.org/downloads/mac-osx/">python.org</a>, or installing
Python using a general OSX package management system such as <aclass="reference external" href="http://brew.sh">homebrew</a> or <aclass="reference external" href="http://www.macports.org">macports</a>. Power users on
OSX 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, Canopy
<spanid="install-osx-binaries"></span><h3>Installing OSX binary wheels<aclass="headerlink" href="#installing-osx-binary-wheels" title="Permalink to this headline">¶</a></h3>
<p>If you are using recent Python from <aclass="reference external" href="http://www.python.org">http://www.python.org</a>, Macports or
Homebrew, then you can use the standard pip installer to install matplotlib
binaries in the form of wheels.</p>
<divclass="section" id="python-org-python">
<h4>Python.org Python<aclass="headerlink" href="#python-org-python" title="Permalink to this headline">¶</a></h4>
<p>Install pip following the <aclass="reference external" href="http://pip.readthedocs.org/en/latest/installing.html">standard pip install instructions</a>. For the impatient,
<h4>Pip problems<aclass="headerlink" href="#pip-problems" title="Permalink to this headline">¶</a></h4>
<p>If you get errors with pip trying to run a compiler like <codeclass="docutils literal"><spanclass="pre">gcc</span></code> or <codeclass="docutils literal"><spanclass="pre">clang</span></code>,
then the first thing to try is to <aclass="reference external" href="https://guide.macports.org/chunked/installing.html#installing.xcode">install xcode</a> and
retry the install. If that does not work, then check
<h3>Installing via OSX mpkg installer package<aclass="headerlink" href="#installing-via-osx-mpkg-installer-package" title="Permalink to this headline">¶</a></h3>
<p>matplotlib also has a disk image (<codeclass="docutils literal"><spanclass="pre">.dmg</span></code>) installer, which contains a
typical Installer.app package to install matplotlib. You should use binary
wheels instead of the disk image installer if you can, because:</p>
<ulclass="simple">
<li>wheels work with Python.org Python, homebrew and macports, the disk image
installer only works with Python.org Python.</li>
<li>The disk image installer doesn’t check for recent versions of packages that
matplotlib depends on, and unconditionally installs the versions of
dependencies contained in the disk image installer. This can overwrite
packages that you have already installed, which might cause problems for
other packages, if you have a pre-existing Python.org setup on your
computer.</li>
</ul>
<p>If you still want to use the disk image installer, read on.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Before installing via the disk image installer, be sure that all of the
packages were compiled for the same version of python. Often, the download
site for NumPy and matplotlib will display a supposed ‘current’ version of
the package, but you may need to choose a different package from the full
list that was built for your combination of python and OSX.</p>
</div>
<p>The disk image installer will have a <codeclass="docutils literal"><spanclass="pre">.dmg</span></code> extension, and will have a name
like <codeclass="file docutils literal"><spanclass="pre">matplotlib-1.4.0-py2.7-macosx10.6.dmg</span></code>.
The name of the installer depends on the versions of python and matplotlib it
was built for, and the version of OSX that the matching Python.org installer
was built for. For example, if the mathing Python.org Python installer was
built for OSX 10.6 or greater, the dmg file will end in <codeclass="docutils literal"><spanclass="pre">-macosx10.6.dmg</span></code>.
You need to download this disk image file, open the disk image file by double
clicking, and find the new matplotlib disk image icon on your desktop. Double
click on that icon to show the contents of the image. Then double-click on
the <codeclass="docutils literal"><spanclass="pre">.mpkg</span></code> icon, which will have a name like
<codeclass="file docutils literal"><spanclass="pre">matplotlib-1.4.0-py2.7-macosx10.6.mpkg</span></code>, it will run the Installer.app,
prompt you for a password if you need system-wide installation privileges, and
<spanid="windows-installers"></span><h3>Standalone binary installers for Windows<aclass="headerlink" href="#standalone-binary-installers-for-windows" title="Permalink to this headline">¶</a></h3>
<p>If you have already installed Python and numpy, you can use one of the
matplotlib binary installers for windows – you can get these from the