Installing an official release#
Matplotlib releases are available as wheel packages for macOS, Windows andLinux on PyPI. Install it usingpip:
python -m pip install -U pippython -m pip install -U matplotlib
If this command results in Matplotlib being compiled from source andthere's trouble with the compilation, you can add --prefer-binary toselect the newest version of Matplotlib for which there is aprecompiled wheel for your OS and Python.
Note
The following backends work out of the box: Agg, ps, pdf, svg
Python is typically shipped with tk bindings which are used byTkAgg.
For support of other GUI frameworks, LaTeX rendering, savinganimations and a larger selection of file formats, you caninstall Optional dependencies.
Third-party distributions#
Various third-parties provide Matplotlib for their environments.
Conda packages#
Matplotlib is available both via the anaconda main channel
conda install matplotlib
as well as via the conda-forge community channel
conda install -c conda-forge matplotlib
Python distributions#
Matplotlib is part of major Python distributions:
- (Video) Python 3.6.3 tutorial - Installation and Introduction
Linux package manager#
If you are using the Python version that comes with your Linux distribution,you can install Matplotlib via your package manager, e.g.:
Debian / Ubuntu:
sudo apt-get install python3-matplotlibFedora:
sudo dnf install python3-matplotlibRed Hat:
sudo yum install python3-matplotlibArch:
sudo pacman -S python-matplotlib
Installing a nightly build#
Matplotlib makes nightly development build wheels available on thescipy-wheels-nightly Anaconda Cloud organization.These wheels can be installed with pip by specifying scipy-wheels-nightlyas the package index to query:
python -m pip install \ --upgrade \ --pre \ --index-url https://pypi.anaconda.org/scipy-wheels-nightly/simple \ --extra-index-url https://pypi.org/simple \ matplotlib
Installing from source#
If you are interested in contributing to Matplotlib development,running the latest source code, or just like to build everythingyourself, it is not difficult to build Matplotlib from source.
First you need to install the Dependencies.
A C compiler is required. Typically, on Linux, you will need gcc, whichshould be installed using your distribution's package manager; on macOS, youwill need xcode; on Windows, you will need Visual Studio 2015 or later.
For those using Visual Studio, make sure "Desktop development with C++" isselected, and that the latest MSVC, "C++ CMake tools for Windows," and aWindows SDK compatible with your version of Windows are selected and installed.They should be selected by default under the "Optional" subheading, but arerequired to build matplotlib from source.
The easiest way to get the latest development version to start contributingis to go to the git repositoryand run:
git clone https://github.com/matplotlib/matplotlib.git
or:
git clone git@github.com:matplotlib/matplotlib.git
If you're developing, it's better to do it in editable mode. The reason whyis that pytest's test discovery only works for Matplotlibif installation is done this way. Also, editable mode allows your code changesto be instantly propagated to your library code without reinstalling (thoughyou will have to restart your python process / kernel):
cd matplotlibpython -m pip install -e .
If you're not developing, it can be installed from the source directory witha simple (just replace the last step):
python -m pip install .
To run the tests you will need to install some additional dependencies:
python -m pip install -r requirements/dev/dev-requirements.txt
Then, if you want to update your Matplotlib at any time, just do:
git pull
When you run git pull, if the output shows that only Python files havebeen updated, you are all set. If C files have changed, you need to run pipinstall -e . again to compile them.
There is more information on using git in the developerdocs.
Warning
The following instructions in this section are for very custominstallations of Matplotlib. Proceed with caution because these instructionsmay result in your build producing unexpected behavior and/or causinglocal testing to fail.
If you would like to build from a tarball, grab the latest tar.gz releasefile from the PyPI files page.
We provide a mplsetup.cfg file which you can use to customize the buildprocess. For example, which default backend to use, whether some of theoptional libraries that Matplotlib ships with are installed, and so on. Thisfile will be particularly useful to those packaging Matplotlib.
If you are building your own Matplotlib wheels (or sdists) on Windows, notethat any DLLs that you copy into the source tree will be packaged too.
Installing for development#
See Setting up Matplotlib for development.
Frequently asked questions#
Report a compilation problem#
See Getting help.
Matplotlib compiled fine, but nothing shows up when I use it#
The first thing to try is a clean install and see ifthat 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 integrateddevelopment environment such as IDLE which add additionalcomplexities. Open up a UNIX shell or a DOS command prompt and run, forexample:
python -c "from pylab import *; set_loglevel('debug'); plot(); show()"
This will give you additional information about which backends Matplotlib isloading, version information, and more. At this point you might want to makesure you understand Matplotlib's configurationprocess, governed by the matplotlibrc configuration file which containsinstructions within and the concept of the Matplotlib backend.
If you are still having trouble, see Getting help.
How to completely remove Matplotlib#
Occasionally, problems with Matplotlib can be solved with a cleaninstallation of the package. In order to fully remove an installed Matplotlib:
Delete the caches from your Matplotlib configuration directory.
Delete any Matplotlib directories or eggs from your installationdirectory.
OSX Notes#
Which python for OSX?#
Apple ships OSX with its own Python, in /usr/bin/python, and its own copyof Matplotlib. Unfortunately, the way Apple currently installs its own copiesof NumPy, Scipy and Matplotlib means that these packages are difficult toupgrade (see system python packages). For that reason we strongly suggestthat you install a fresh version of Python and use that as the basis forinstalling libraries such as NumPy and Matplotlib. One convenient way toinstall Matplotlib with other useful Python software is to use the AnacondaPython scientific software collection, which includes Python itself and awide range of libraries; if you need a library that is not available from thecollection, you can install it yourself using standard methods such as pip.See the Anaconda web page for installation support.
Other options for a fresh Python install are the standard installer frompython.org, or installingPython using a general OSX package management system such as homebrew or macports. Power users onOSX will likely want one of homebrew or macports on their system to installopen source software packages, but it is perfectly possible to use thesesystems with another source for your Python binary, such as Anacondaor Python.org Python.
Installing OSX binary wheels#
If you are using Python from https://www.python.org, Homebrew, or Macports,then you can use the standard pip installer to install Matplotlib binaries inthe form of wheels.
pip is installed by default with python.org and Homebrew Python, but needs tobe manually installed on Macports with
sudo port install py38-pip
Once pip is installed, you can install Matplotlib and all its dependencies withfrom the Terminal.app command line:
python3 -m pip install matplotlib
You might also want to install IPython or the Jupyter notebook (python3 -m pipinstall ipython notebook).
Checking your installation#
The new version of Matplotlib should now be on your Python "path". Check thisat the Terminal.app command line:
python3 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)'
You should see something like
3.6.0 /Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages/matplotlib/__init__.py
where 3.6.0 is the Matplotlib version you just installed, and the pathfollowing depends on whether you are using Python.org Python, Homebrew orMacports. If you see another version, or you get an error like
Traceback (most recent call last): File "<string>", line 1, in <module>ImportError: No module named matplotlib
then check that the Python binary is the one you expected by running
which python3
If you get a result like /usr/bin/python..., then you are getting thePython installed with OSX, which is probably not what you want. Try closingand restarting Terminal.app before running the check again. If that doesn't fixthe problem, depending on which Python you wanted to use, consider reinstallingPython.org Python, or check your homebrew or macports setup. Remember thatthe disk image installer only works for Python.org Python, and will not getpicked up by other Pythons. If all these fail, please let us know.