Runtime dependencies

Mandatory dependencies

When installing through a package manager like pip or conda, the mandatory dependencies are automatically installed. This list is mainly for reference.

Optional dependencies

The following packages and tools are not required but extend the capabilities of Matplotlib.


Matplotlib figures can be rendered to various user interfaces. See What is a backend? for more details on the optional Matplotlib backends and the capabilities they provide.

  • Tk (>= 8.3, != 8.6.0 or 8.6.1) [1]: for the Tk-based backends.
  • PyQt4 (>= 4.6) or PySide (>= 1.0.3) [2]: for the Qt4-based backends.
  • PyQt5 or PySide2: for the Qt5-based backends.
  • PyGObject: for the GTK3-based backends [3].
  • wxPython (>= 4) [4]: for the wx-based backends.
  • pycairo (>= 1.11.0) or cairocffi (>= 0.8): for the GTK3 and/or cairo-based backends.
  • Tornado: for the WebAgg backend.
[1]Tk is part of most standard Python installations, but it's not part of Python itself and thus may not be present in rare cases.
[2]PySide cannot be pip-installed on Linux (but can be conda-installed).
[3]If using pip (and not conda), PyGObject must be built from source; see
[4]If using pip (and not conda) on Linux, wxPython wheels must be manually downloaded from


Font handling and rendering

C libraries

Matplotlib brings its own copies of the following libraries:

  • Agg: the Anti-Grain Geometry C++ rendering engine
  • ttconv: a TrueType font utility

Additionally, Matplotlib depends on:

  • FreeType (>= 2.3): a font rendering library
  • QHull (>= 2020.2): a library for computing triangulations

By default, Matplotlib downloads and builds its own copies of FreeType (this is necessary to run the test suite, because different versions of FreeType rasterize characters differently) and of Qhull. As an exception, Matplotlib defaults to the system version of FreeType on AIX.

To force Matplotlib to use a copy of FreeType or Qhull already installed in your system, create a setup.cfg file with the following contents:

system_freetype = true
system_qhull = true

before running python -m pip install ..

In this case, you need to install the FreeType and Qhull library and headers. This can be achieved using a package manager, e.g. for FreeType:

# Pick ONE of the following:
sudo apt install libfreetype6-dev  # Debian/Ubuntu
sudo dnf install freetype-devel    # Fedora
brew install freetype              # macOS with Homebrew
conda install freetype             # conda, any OS

(adapt accordingly for Qhull).

On Linux and macOS, it is also recommended to install pkg-config, a helper tool for locating FreeType:

# Pick ONE of the following:
sudo apt install pkg-config  # Debian/Ubuntu
sudo dnf install pkgconf     # Fedora
brew install pkg-config      # macOS with Homebrew
conda install pkg-config     # conda
# Or point the PKG_CONFIG environment variable to the path to pkg-config:
export PKG_CONFIG=...

If not using pkg-config (in particular on Windows), you may need to set the include path (to the library headers) and link path (to the libraries) explicitly, if they are not in standard locations. This can be done using standard environment variables -- on Linux and OSX:

export CFLAGS='-I/directory/containing/ft2build.h'
export LDFLAGS='-L/directory/containing/'

and on Windows:

set CL=/IC:\directory\containing\ft2build.h
set LINK=/LIBPATH:C:\directory\containing\freetype.lib

If you go this route but need to reset and rebuild to change your settings, remember to clear your artifacts before re-building:

git clean -xfd

Additional dependencies for development

Additional dependencies for testing

This section lists the additional software required for running the tests.



Additional dependencies for building documentation

Python packages

The additional Python packages required to build the documentation are listed in doc-requirements.txt and can be installed using

pip install -r requirements/doc/doc-requirements.txt

The content of doc-requirements.txt is also shown below:

# Requirements for building docs
# You will first need a matching Matplotlib installation
# e.g (from the Matplotlib root directory)
#     pip install -e .
# Install the documentation requirements with:
#     pip install -r requirements/doc/doc-requirements.txt
# sphinx-gallery>=0.7   
# b41e328 is PR 808 which adds the image_srcset directive.  When this is 
# released with sphinx gallery, we can change to the last release w/o this feature:
# sphinx-gallery>0.90

Additional external dependencies


  • a minimal working LaTeX distribution
  • Graphviz
  • the LaTeX packages cm-super and dvipng (if your OS bundles TeXLive, the "complete" version of the installer, e.g. "texlive-full" or "texlive-all", will often automatically include these packages)

Optional, but recommended:

  • Inkscape
  • optipng
  • the font "Humor Sans" (aka the "XKCD" font), or the free alternative Comic Neue
  • the font "Times New Roman"


The documentation will not build without LaTeX and Graphviz. These are not Python packages and must be installed separately. The documentation can be built without Inkscape and optipng, but the build process will raise various warnings. If the build process warns that you are missing fonts, make sure your LaTeX distribution bundles cm-super or install it separately.