When installing through a package manager like
mandatory dependencies are automatically installed. This list is mainly for
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.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.
Tornado (>= 5): for the WebAgg backend.
ipykernel: for the nbagg backend.
macOS (>= 10.12): for the macosx backend.
Font handling and rendering#
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.
Use system libraries#
To force Matplotlib to use a copy of FreeType or Qhull already installed in
your system, create a
mplsetup.cfg file with the following contents:
[libs] system_freetype = true system_qhull = true
python -m pip install .
You can also use the
MPLSETUPCFG to specify the path to a cfg file when
installing from pypi.
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/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
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 and unpack the tarballs into:
build/freetype-2.6.1 # on all platforms but windows ARM64 build/freetype-2.11.1 # on windows ARM64 build/qhull-2020.2
at the top level of the checkout repository. The expected sha256 hashes of
the downloaded tarballs is in
setupext.py if you wish to verify
Minimum pip / manylinux support (linux)#
Matplotlib publishes manylinux wheels which have a minimum version of pip which will recognize the wheels
manylinx2014/ pip >= 19.3
In all cases the required version of pip is embedded in the CPython source.
Dependencies for building Matplotlib#
certifi (>= 2020.06.20). Used while downloading the freetype and QHull source during build. This is not a runtime dependency.
PyBind11 (>= 2.6). Used to connect C/C++ code with Python.
setuptools (>= 64).
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.21). Also a runtime dependency.
Matplotlib requires a C++ compiler that supports C++11, and each platform has a development environment that must be installed before a compiler can be installed.
On some Linux systems, you can install a meta-build package. For example,
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.
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:
Linux, macOS, Windows
For gcc <6.5 you will need to set
Dependencies for testing Matplotlib#
This section lists the additional software required for running the tests.
pytest (>= 7.0.0)
In addition to all of the optional dependencies on the main library, for testing the following will be used if they are installed.
Ghostscript (>= 9.0, to render PDF files)
Inkscape (to render SVG files)
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
WenQuanYi Zen Hei and Noto Sans CJK fonts for testing font fallback and non-western fonts
xarray used to test compatibility with xarray
If any of these dependencies are not discovered, then the tests that rely on them will be skipped by pytest.
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.
Dependencies for building Matplotlib's documentation#
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>=3.0.0,!=6.1.2 colorspacious ipython ipywidgets ipykernel numpydoc>=1.0 packaging>=20 pydata-sphinx-theme~=0.13.1 mpl-sphinx-theme~=3.8.0 pyyaml sphinxcontrib-svg2pdfconverter>=1.1.0 sphinx-gallery>=0.12.0 sphinx-copybutton sphinx-design
Additional external dependencies#
the following LaTeX packages (if your OS bundles TeX Live, the "complete" version of the installer, e.g. "texlive-full" or "texlive-all", will often automatically include these packages):
Optional, but recommended:
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.