Setting up Matplotlib for development#

To set up Matplotlib for development follow these steps:

Fork the Matplotlib repository#

Matplotlib is hosted at matplotlib/matplotlib.git. If you plan on solving issues or submit pull requests to the main Matplotlib repository, you should first fork this repository by visiting matplotlib/matplotlib.git and clicking on the Fork button on the top right of the page (see the GitHub documentation for more details.)

Retrieve the latest version of the code#

Now that your fork of the repository lives under your GitHub username, you can retrieve the latest sources with one of the following commands (where your should replace <your-username> with your GitHub username):

git clone https://github.com/<your-username>/matplotlib.git

git clone [email protected]:<your-username>/matplotlib.git

This requires you to setup an SSH key in advance, but saves you from typing your password at every connection.

This will place the sources in a directory matplotlib below your current working directory, set up the origin remote to point to your own fork, and set up the upstream remote to point to the Matplotlib main repository (see also Managing remote repositories.) Change into this directory before continuing:

cd matplotlib

Note

For more information on git and GitHub, check the following resources.

Create a dedicated environment#

You should set up a dedicated environment to decouple your Matplotlib development from other Python and Matplotlib installations on your system.

The simplest way to do this is to use either Python's virtual environment venv or conda.

Create a new venv environment with

python -m venv <file folder location>

and activate it 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

On some systems, you may need to type python3 instead of python. For a discussion of the technical reasons, see PEP-394.

Create a new conda environment with

conda env create -f environment.yml

You can use mamba instead of conda in the above command if you have mamba installed.

Activate the environment using

conda activate mpl-dev

Remember to activate the environment whenever you start working on Matplotlib.

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 .

Install pre-commit hooks (optional)#

pre-commit hooks automatically check flake8 and other style issues when you run git commit. The hooks are defined in the top level .pre-commit-config.yaml file. To install the hooks

python -m pip install pre-commit
pre-commit install

The hooks can also be run manually. All the hooks can be run, in order as listed in .pre-commit-config.yaml, against the full codebase with

pre-commit run --all-files

To run a particular hook manually, run pre-commit run with the hook id

pre-commit run <hook id> --all-files