Ctrl+K

Dependencies#

Runtime dependencies#

Required#

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

Optional#

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

Backends#

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.5, != 8.6.0 or 8.6.1): for the Tk-based backends. 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.

  • PyQt6 (>= 6.1), PySide6, PyQt5 (>= 5.12), or PySide2: for the Qt-based backends.

  • PyGObject and pycairo (>= 1.14.0): for the GTK-based backends. If using pip (but not conda or system package manager) PyGObject must be built from source; see pygobject documentation.

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

  • wxPython (>= 4): for the wx-based backends. If using pip (but not conda or system package manager) on Linux wxPython wheels must be manually downloaded from https://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 is also 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, because different 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 must pass configuration settings to Meson via meson-python:

python -m pip install \
  --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:
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 macOS:

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

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

From source files#

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

Minimum pip / manylinux support (linux)#

Matplotlib publishes manylinux wheels which 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#

By default, pip will build packages using build isolation, meaning that these build dependencies are temporally installed by pip for the duration of the Matplotlib build process. However, build isolation is disabled when installing Matplotlib for development; therefore we recommend using one of our virtual environment configurations to create a development environment in which these packages are automatically installed.

If you are developing Matplotlib and unable to use our environment configurations, then you must manually install the following packages into your development environment:

  • meson-python (>= 0.13.1).

  • ninja (>= 1.8.2). This may be available in your package manager or bundled with Meson, but may be installed via pip if otherwise not available.

  • PyBind11 (>= 2.6). Used to connect C/C++ code with Python.

  • setuptools_scm (>= 7). Used to update the reported mpl.__version__ based on the current git commit. Also a runtime dependency for editable installs.

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

Compiled extensions#

Matplotlib requires a C++ compiler that supports C++17, and each platform has a development 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 extension source files.

On some Linux systems, you can install a meta-build package. For example, on Ubuntu apt install build-essential

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

Install Xcode for Apple platform development.

Install Visual 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 version of Windows are selected and installed. They should be selected by default under the "Optional" subheading, but are required to build Matplotlib from source.

Alternatively, you can install a Linux-like environment such as CygWin or Windows Subsystem for Linux. If using MinGW-64, we require v6 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. Choose one 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 for running the tests.

Required#

Optional#

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

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

Note

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

Documentation dependencies#

Python#

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 --no-build-isolation --editable .[dev]
#
# Install the documentation requirements with:
#     pip install -r requirements/doc/doc-requirements.txt
#
sphinx>=3.0.0,!=6.1.2
colorspacious
ipython
ipywidgets
ipykernel
numpydoc>=1.0
packaging>=20
pydata-sphinx-theme~=0.15.0
mpl-sphinx-theme~=3.9.0
pyyaml
sphinxcontrib-svg2pdfconverter>=1.1.0
sphinx-copybutton
sphinx-design
sphinx-gallery>=0.12.0
sphinx-tags>=0.3.0

External tools#

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

Required#

The following LaTeX packages:

The complete version of many LaTex distribution installers, e.g. "texlive-full" or "texlive-all", will often automatically include these packages.

Optional#

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

On this page