python -m pip install -U pip
python -m pip install -U matplotlib
If this command results in Matplotlib being compiled from source and
there's trouble with the compilation, you can add --prefer-binary to
select the newest version of Matplotlib for which there is a
precompiled wheel for your OS and Python.
The following backends work out of the box: Agg, ps, pdf, svg
Python is typically shipped with tk bindings which are used by
TkAgg.
For support of other GUI frameworks, LaTeX rendering, saving
animations and a larger selection of file formats, you can
install 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
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-matplotlib
Fedora: sudo dnf install python3-matplotlib
Red Hat: sudo yum install python3-matplotlib
Arch: sudo pacman -S python-matplotlib
Install a nightly build
Matplotlib makes nightly development build wheels available on the
scientific-python-nightly-wheels Anaconda Cloud organization.
These wheels can be installed with pip by specifying
scientific-python-nightly-wheels as the package index to query:
python -m pip install \
--upgrade \
--pre \
--index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \
--extra-index-url https://pypi.org/simple \
matplotlib
Installing for Development
If you would like to contribute to Matplotlib or otherwise need to
install the latest development code, please follow the instructions in
Setting up Matplotlib for development.
The following instructions are for installing from source for production use.
This is generally not recommended; please use prebuilt packages when possible.
Proceed with caution because these instructions may result in your
build producing unexpected behavior and/or causing local testing to fail.
Before trying to install Matplotlib, please install the Dependencies.
To build from a tarball, download the latest tar.gz release
file from the PyPI files page.
We provide a mplsetup.cfg 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.
If you are building your own Matplotlib wheels (or sdists) on Windows, note
that any DLLs that you copy into the source tree will be packaged too.
Configure build and behavior defaults
Aspects of the build and install process and some behaviorial defaults of the
library can be configured via Environment variables. Default plotting
appearance and behavior can be configured via the
rcParams file
Frequently asked questions
Report a compilation problem
See Get help.
Matplotlib compiled fine, but nothing shows up when I use it
The first thing to try is a clean install 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 IDLE which add additional
complexities. Open up a UNIX shell or a DOS command prompt and run, for
example:
python -c "from pylab import *; set_loglevel('debug'); plot(); show()"
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 configuration
process, governed by the matplotlibrc configuration file which contains
instructions within and the concept of the Matplotlib backend.
If you are still having trouble, see Get help.
How to completely remove Matplotlib
Occasionally, problems with Matplotlib can be solved with a clean
installation 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 installation
directory.
OSX Notes
Which python for OSX?
Apple ships OSX with its own Python, in /usr/bin/python, 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 system python packages). 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 Anaconda
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 pip.
See the Anaconda web page for installation support.
Other options for a fresh Python install are the standard installer from
python.org, or installing
Python using a general OSX package management system such as homebrew or macports. 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
or 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 in
the form of wheels.
pip is installed by default with python.org and Homebrew Python, but needs to
be manually installed on Macports with
sudo port install py38-pip
Once pip is installed, you can install Matplotlib and all its dependencies with
from the Terminal.app command line:
python3 -m pip install matplotlib
You might also want to install IPython or the Jupyter notebook (python3 -m pip
install ipython notebook).
Checking your installation
The new version of Matplotlib should now be on your Python "path". Check this
at 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 path
following depends on whether you are using Python.org Python, Homebrew or
Macports. 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 the
Python installed with OSX, 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 let us know.
Troubleshooting
Obtaining Matplotlib version
To find out your Matplotlib version number, import it and print the
__version__ attribute:
>>> import matplotlib
>>> matplotlib.__version__
'0.98.0'
matplotlib install location
You can find what directory Matplotlib is installed in by importing it
and printing the __file__ attribute:
>>> import matplotlib
>>> matplotlib.__file__
'/home/jdhunter/dev/lib64/python2.5/site-packages/matplotlib/__init__.pyc'
matplotlib configuration and cache directory locations
Each user has a Matplotlib configuration directory which may contain a
matplotlibrc file. To
locate your matplotlib/ configuration directory, use
matplotlib.get_configdir():
>>> import matplotlib as mpl
>>> mpl.get_configdir()
'/home/darren/.config/matplotlib'
On Unix-like systems, this directory is generally located in your
HOME directory under the .config/ directory.
In addition, users have a cache directory. On Unix-like systems, this is
separate from the configuration directory by default. To locate your
.cache/ directory, use matplotlib.get_cachedir():
>>> import matplotlib as mpl
>>> mpl.get_cachedir()
'/home/darren/.cache/matplotlib'
On Windows, both the config directory and the cache directory are
the same and are in your Documents and Settings or Users
directory by default:
>>> import matplotlib as mpl
>>> mpl.get_configdir()
'C:\\Documents and Settings\\jdhunter\\.matplotlib'
>>> mpl.get_cachedir()
'C:\\Documents and Settings\\jdhunter\\.matplotlib'
If you would like to use a different configuration directory, you can
do so by specifying the location in your MPLCONFIGDIR
environment variable -- see
Setting environment variables in Linux and macOS. Note that
MPLCONFIGDIR sets the location of both the configuration
directory and the cache directory.
Frequently asked questions
