Dependencies#

Runtime dependencies#

Required#

When installing through a package manager likepip orconda, themandatory dependencies are automatically installed. This list is mainly forreference.

Optional#

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

Backends#

Matplotlib figures can be rendered to various user interfaces. SeeWhat is a backend? for more details on the optional Matplotlib backendsand the capabilities they provide.

  • Tk (>= 8.5, != 8.6.0 or 8.6.1): for the Tk-based backends. Tk is part ofmost standard Python installations, but it's not part of Python itself andthus may not be present in rare cases.

  • PyQt6 (>= 6.1),PySide6,PyQt5 (>= 5.12), orPySide2: for the Qt-basedbackends.

  • PyGObject andpycairo (>= 1.14.0): for the GTK-based backends. If using pip(but not conda or system package manager) PyGObject must be built fromsource; seepygobject documentation.

  • pycairo (>= 1.14.0) orcairocffi (>= 0.8): for cairo-based backends.

  • wxPython (>= 4): for the wx-based backends. If using pip (but not conda orsystem package manager) on Linux wxPython wheels must be manually downloadedfromhttps://wxpython.org/pages/downloads/.

  • Tornado (>= 5): for the WebAgg backend.

  • ipykernel: for the nbagg backend.

  • macOS (>= 10.12): for the macosx backend.

Animations#

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 (>= 8.0.2): a library for computing triangulations (note that this version isalso known as 2020.2)

Download during install#

By default, Matplotlib downloads and builds its own copies of Qhull and FreeType.The vendored version of FreeType is necessary to run the test suite, becausedifferent versions of FreeType rasterize characters differently.

Use system libraries#

To force Matplotlib to use a copy of FreeType or Qhull already installed in your system,you mustpass configuration settings to Meson via meson-python:

python-mpipinstall\--config-settings=setup-args="-Dsystem-freetype=true"\--config-settings=setup-args="-Dsystem-qhull=true"\.

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:sudoaptinstalllibfreetype6-dev# Debian/Ubuntusudodnfinstallfreetype-devel# Fedorabrewinstallfreetype# macOS with Homebrewcondainstallfreetype# conda, any OS

(adapt accordingly for Qhull).

On Linux and macOS, it is also recommended to installpkg-config, a helpertool for locating FreeType:

# Pick ONE of the following:sudoaptinstallpkg-config# Debian/Ubuntusudodnfinstallpkgconf# Fedorabrewinstallpkg-config# macOS with Homebrewcondainstallpkg-config# conda# Or point the PKG_CONFIG environment variable to the path to pkg-config:exportPKG_CONFIG=...

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

exportCFLAGS='-I/directory/containing/ft2build.h'exportLDFLAGS='-L/directory/containing/libfreetype.so'

and on Windows:

setCL=/IC:\directory\containing\ft2build.hsetLINK=/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:

gitclean-xfd

From source files#

If the automatic download does not work (for example, on air-gapped systems) it ispreferable to instead use system libraries. However you can manually download thetarballs intosubprojects/packagecache at the top level of the checkoutrepository. The expected SHA256 hashes of the downloaded tarballs are insubprojects/*.wrap if you wish to verify them, but they will also be checked bythe build system before unpacking.

Minimum pip / manylinux support (linux)#

Matplotlib publishesmanylinux wheelswhich have a minimum version of pip which will recognize the wheels

  • Python 3.9+:manylinux2014 / pip >= 19.3

In all cases the required version of pip is embedded in the CPython source.

Build dependencies#

Python#

pip normally builds packages usingbuild isolation,which means thatpip installs the dependencies listed here for theduration of the build process. However, build isolation is disabled via the the--no-build-isolation flagwheninstalling Matplotlib for development, whichmeans that the dependencies must be explicitly installed, either bycreating a virtual environment(recommended) or by manually installing the following packages:

  • meson-python (>= 0.13.1).

  • PyBind11 (>= 2.13.2). Used to connect C/C++ codewith Python.

  • setuptools_scm (>= 7). Used toupdate the reportedmpl.__version__ based on the current git commit.Also a runtime dependency for editable installs.

  • NumPy (>= 1.22). Also a runtime dependency.

Compilers and external build tools#

When setting up a virtual environment for development,ninja(>= 1.8.2) may need to be installed separately. This may be availableas apre-built binary or from apackage manageror bundled with Meson. Ninja may also be installed viapip if otherwise notavailable.

Compilers#

Matplotlib requires a C++ compiler that supports C++17, and each platform has adevelopment environment that must be installed before a compiler can be installed.You may also need to install headers for various libraries used in the compiled extensionsource files.

On some Linux systems, you can install a meta-build package. For example,on Ubuntuaptinstallbuild-essential with elevated privileges.

Otherwise, use the system distribution's package manager to installgcc.

InstallXcode for Apple platform development.

InstallVisual Studio Build Tools

Make sure "Desktop development with C++" is selected, and that the latest MSVC,"C++ CMake tools for Windows," and a Windows SDK compatible with your versionof Windows are selected and installed. They should be selected by default underthe "Optional" subheading, but are required to build Matplotlib from source.

Alternatively, you can install a Linux-like environment such asCygWinorWindows Subsystem for Linux.If usingMinGW-64, we requirev6 of the`Mingw-w64-x86_64-headers.

We highly recommend that you install a compiler using your platform tool, i.e., Xcode,VS Code or Linux package manager. Chooseone compiler from this list:

compiler

minimum version

platforms

notes

GCC

7.2

Linux, macOS, Windows

gcc 7.2,GCC: Binaries,

Clang (LLVM)

5

Linux, macOS

clang 5,LLVM

MSVC++

16.0

Windows

Visual Studio 2019 C++

Test dependencies#

This section lists the additional software required forrunning the tests.

Required#

Optional#

In addition to all of the optional dependencies on the main library, fortesting the following will be used if they are installed.

Python#

These packages are installed whencreating a virtual environment,otherwise they must be installed manually:

  • nbformat andnbconvert used to test the notebook backend

  • pandas used to test compatibility with Pandas

  • pikepdf used in some tests for the pgf and pdf backends

  • psutil used in testing the interactive backends

  • pytest-cov (>= 2.3.1) to collect coverage information

  • pytest-timeout to limit runtime in case of stuck tests

  • pytest-xdist to run tests in parallel

  • pytest-xvfb to run tests without windows popping up (Linux)

  • pytz used to test pytz int

  • sphinx used to test our sphinx extensions

  • xarray used to test compatibility with xarray

External tools#

If any of these dependencies are not discovered, then the tests that rely onthem will be skipped by pytest.

Note

When installing Inkscape on Windows, make sure that you select “AddInkscape to system PATH”, either for all users or current user, or thetests will not find it.

Documentation dependencies#

Python#

The additional Python packages required to build thedocumentation are listed indoc-requirements.txt and can be installed using

pipinstall-rrequirements/doc/doc-requirements.txt

The content ofdoc-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 --no-build-isolation --editable .[dev]## Install the documentation requirements with:#     pip install -r requirements/doc/doc-requirements.txt#sphinx>=5.1.0,!=6.1.2colorspaciousipythonipywidgetsipykernelnumpydoc>=1.0packaging>=20pydata-sphinx-theme~=0.15.0mpl-sphinx-theme~=3.9.0pyyamlPyStemmersphinxcontrib-svg2pdfconverter>=1.1.0sphinxcontrib-video>=0.2.1sphinx-copybuttonsphinx-designsphinx-gallery[parallel]>=0.12.0sphinx-tags>=0.4.0

External tools#

Required#

The documentation requires LaTeX and Graphviz. These are notPython packages and must be installed separately.

LaTeX dependencies#

The following collections must be installed. When using a distribution that does notsupport collections, the packages listed for each collection must be installed. You mayneed to install some packages that are not listed here. The complete version of manyLaTeX distribution installers, e.g. "texlive-full" or "texlive-all",will often automatically include these collections.

collection

packages

collection-basic

cm,luahbtex

collection-fontsrecommended

cm-super,lm,txfonts

collection-latex

fix-cm,geometry,hyperref,latex,latex-bin,psnfss

collection-latexextra

import,sfmath,type1cm

collection-latexrecommended

fontspec,underscore,

collection-xetex

xetex,xetex-bin

The following packages must also be installed:

Optional#

The documentation can be built without Inkscape and optipng, but the buildprocess will raise various warnings.