Setting up Matplotlib for development

Creating a dedicated environment

You should set up a dedicated environment to decouple your Matplotlib development from other Python and Matplotlib installations on your system. Here we use python's virtual environment venv, but you may also use others such as conda.

A new environment can be set up with

python -m venv <file folder location>

and activated with one of the following:

source <file folder location>/bin/activate  # Linux/macOS
<file folder location>\Scripts\activate.bat  # Windows cmd.exe
<file folder location>\Scripts\Activate.ps1  # Windows PowerShell

Whenever you plan to work on Matplotlib, remember to activate the development environment in your shell.

Retrieving the latest version of the code

Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git.

You can retrieve the latest sources with the command (see Set up your fork for more details):

git clone https://github.com/matplotlib/matplotlib.git

This will place the sources in a directory matplotlib below your current working directory.

If you have the proper privileges, you can use git@ instead of https://, which works through the ssh protocol and might be easier to use if you are using 2-factor authentication.

Installing Matplotlib in editable mode

Install Matplotlib in editable mode from the matplotlib directory using the command

python -m pip install -ve .

The 'editable/develop mode', builds everything and places links in your Python environment so that Python will be able to import Matplotlib from your development source directory. This allows you to import your modified version of Matplotlib without re-installing after every change. Note that this is only true for *.py files. If you change the C-extension source (which might also happen if you change branches) you will have to re-run python -m pip install -ve .

Additional dependencies for testing

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

Required:

Optional:

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>=1.8.1,!=2.0.0
colorspacious
ipython
ipywidgets
numpydoc>=0.8
sphinxcontrib-svg2pdfconverter>=1.1.0
sphinx-gallery>=0.7
sphinx-copybutton
scipy

Additional external dependencies

Required:

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

Optional, but recommended:

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

Note

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.