Installation#

pipinstallmatplotlib
condainstall-cconda-forgematplotlib
pixiaddmatplotlib
uvaddmatplotlib

Warning

uv usually installs its own versions of Python from thepython-build-standalone project, and only recent versions of thosePython builds (August 2025) work properly with thetkagg backendfor displaying plots in a window. Please make sure you are using uv0.8.7 or newer (update with e.g.uvselfupdate) and that yourbundled Python installs are up to date (withuvpythonupgrade--reinstall). Alternatively, you can use one of the othersupported GUI frameworks, e.g.

uvaddmatplotlibpyside6

Install an official release#

Matplotlib releases are available as wheel packages for macOS, Windows andLinux onPyPI. Install it usingpip:

python-mpipinstall-Upippython-mpipinstall-Umatplotlib

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 non-interactive backends work out of the box: Agg,ps, pdf, svg

The TkAgg interactive backend also typically works out of the box.It requires Tk bindings, which are usually provided via the Pythonstandard library'stkinter module. On some OSes, you may needto install a separate package likepython3-tk to add thiscomponent of the standard library.

Some tools likeuv make use of Python builds from thepython-build-standalone project, which only gained usable Tkbindings recently (August 2025). If you are having trouble with theTkAgg backend, ensure you have an up-to-date build, e.g.uvselfupdate&&uvpythonupgrade--reinstall.

For support of other GUI frameworks, LaTeX rendering, savinganimations and a larger selection of file formats, you caninstalloptional dependencies.

Third-party distributions#

Various third-parties provide Matplotlib for their environments.

Conda packages#

Matplotlib is available both via theanaconda main channel

condainstallmatplotlib

as well as via theconda-forge community channel

condainstall-cconda-forgematplotlib

Python distributions#

Matplotlib is part of major Python distributions:

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:sudoapt-getinstallpython3-matplotlib

  • Fedora:sudodnfinstallpython3-matplotlib

  • Red Hat:sudoyuminstallpython3-matplotlib

  • Arch:sudopacman-Spython-matplotlib

Install a nightly build#

Matplotlib makes nightly development build wheels available on thescientific-python-nightly-wheels Anaconda Cloud organization.These wheels can be installed withpip by specifyingscientific-python-nightly-wheels as the package index to query:

python-mpipinstall\--upgrade\--pre\--index-urlhttps://pypi.anaconda.org/scientific-python-nightly-wheels/simple\--extra-index-urlhttps://pypi.org/simple\matplotlib

Install from source#

Installing for Development

If you would like to contribute to Matplotlib or otherwise need toinstall the latest development code, please follow the instructions inSetting up Matplotlib for development.

The following instructions are for installing from source for production use.This is generallynot recommended; please use prebuilt packages when possible.Proceed with caution because these instructions may result in yourbuild producing unexpected behavior and/or causing local testing to fail.

Before trying to install Matplotlib, please install theDependencies.

To build from a tarball, download the latesttar.gz releasefile fromthe PyPI files page.

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.

Configure build and behavior defaults#

We provide ameson.options file containing options with which you can use tocustomize the build process. For example, which default backend to use, whether some ofthe optional libraries that Matplotlib ships with are installed, and so on. Theseoptions will be particularly useful to those packaging Matplotlib.

Aspects of some behavioral defaults of the library can be configured via:

Default plotting appearance and behavior can be configured via thercParams file.

Dependencies#

Mandatory dependencies should be installed automatically if you install Matplotlib usinga package manager such aspip orconda; therefore this list is primarily forreference and troubleshooting.

Frequently asked questions#

Report a compilation problem#

SeeGet help.

Matplotlib compiled fine, but nothing shows up when I use it#

The first thing to try is aclean 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 asIDLE 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'sconfigurationprocess, governed by thematplotlibrc configuration file which containsinstructions within and the concept of the Matplotlib backend.

If you are still having trouble, seeGet 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:

  1. Delete the caches from yourMatplotlib configuration directory.

  2. Delete any Matplotlib directories or eggs from yourinstallationdirectory.

macOS Notes#

Which python for macOS?#

Apple ships macOS 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 (seesystem 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 theAnacondaPython 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 aspip.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 macOS package management system such ashomebrew ormacports. Power users onmacOS 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 macOS binary wheels#

If you are using Python fromhttps://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

sudoportinstallpy38-pip

Once pip is installed, you can install Matplotlib and all its dependencies withfrom the Terminal.app command line:

python3-mpipinstallmatplotlib

You might also want to install IPython or the Jupyter notebook (python3-mpipinstallipythonnotebook).

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.10.0 /Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/matplotlib/__init__.py

where3.10.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

whichpython3

If you get a result like/usr/bin/python..., then you are getting thePython installed with macOS, 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, pleaselet us know.

Troubleshooting#

Obtaining Matplotlib version#

To find out your Matplotlib version number, import it and print the__version__ attribute:

>>>importmatplotlib>>>matplotlib.__version__'0.98.0'

matplotlib install location#

You can find what directory Matplotlib is installed in by importing itand printing the__file__ attribute:

>>>importmatplotlib>>>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 amatplotlibrc file. Tolocate yourmatplotlib/ configuration directory, usematplotlib.get_configdir():

>>>importmatplotlibasmpl>>>mpl.get_configdir()'/home/darren/.config/matplotlib'

On Unix-like systems, this directory is generally located in yourHOME directory under the.config/ directory.

In addition, users have a cache directory. On Unix-like systems, this isseparate from the configuration directory by default. To locate your.cache/ directory, usematplotlib.get_cachedir():

>>>importmatplotlibasmpl>>>mpl.get_cachedir()'/home/darren/.cache/matplotlib'

On Windows, both the config directory and the cache directory arethe same and are in yourDocumentsandSettings orUsersdirectory by default:

>>>importmatplotlibasmpl>>>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 cando so by specifying the location in yourMPLCONFIGDIRenvironment variable -- seeSetting environment variables in Linux and macOS. Note thatMPLCONFIGDIR sets the location of both the configurationdirectory and the cache directory.