Setting up Matplotlib for development#

To set up Matplotlib for development follow these steps:

Fork the Matplotlib repository#

Matplotlib is hosted atmatplotlib/matplotlib.git. If youplan on solving issues or submitting pull requests to the main Matplotlibrepository, you should first fork this repository byclicking theFork button near the top of theproject repository page.

This creates a copy of the code under your account on the GitHub server. Seethe GitHubdocumentation for more details.

Set up development environment#

You can either work locally on your machine, or online inGitHub Codespaces, a cloud-based in-browser developmentenvironment.

local:

If you are making extensive or frequent contributions to Matplotlib then itis probably worth taking the time to set up on your local machine: As well ashaving the convenience of your local familiar tools, you will not need to worryabout Codespace's monthly usage limits.

codespaces:

If you are making a one-off, relatively simple, change then working inGitHub Codespaces can be a good option because most of the settingup is done for you and you can skip the next few sections.

If you want to use Codespaces, skip toCreate GitHub Codespace,otherwise, continue with the next section.

Create local environment#

Get most recent code#

Now that your fork of the repository lives under your GitHub username, you canretrieve the most recent version of the source code with one of the followingcommands (replace<your-username> with your GitHub username):

gitclonehttps://github.com/<your-username>/matplotlib.git
gitclone[email protected]:<your-username>/matplotlib.git

This requires you to setup anSSH key in advance, but saves you fromtyping your password at every connection.

This will place the sources in a directorymatplotlib below yourcurrent working directory and set the remote nameorigin to point to yourfork. Change into this directory before continuing:

cdmatplotlib

Now set the remote nameupstream to point to the Matplotlib main repository:

gitremoteaddupstreamhttps://github.com/matplotlib/matplotlib.git
gitremoteaddupstream[email protected]:matplotlib/matplotlib.git

You can now useupstream to retrieve the most current snapshot of the sourcecode, as described inDevelopment workflow.

Additionalgit andGitHub resources

Create a dedicated environment#

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

We recommend using one of the following options for a dedicated development environmentbecause these options are configured to install the Python dependencies as part of theirsetup.

Create a newvenv environment with

python-mvenv<filefolderlocation>

and activate it with one of the following :

source<filefolderlocation>/bin/activate# Linux/macOS
<file folder location>\Scripts\activate.bat
<file folder location>\Scripts\Activate.ps1

On some systems, you may need to typepython3 instead ofpython.For a discussion of the technical reasons, seePEP-394.

Install the Python dependencies with

pipinstall-rrequirements/dev/dev-requirements.txt

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

Create a newconda environment and install the Python dependencies with

condaenvcreate-fenvironment.yml

You can usemamba instead ofconda in the above command ifyou havemamba installed.

Activate the environment using

condaactivatempl-dev

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

Install external dependencies#

Python dependencies were installed as part ofsetting up the environment.Additionally, the following non-Python dependencies must also be installed locally:

For a full list of dependencies, seeDependencies. External dependencies do notneed to be installed when working in codespaces.

Create GitHub Codespace#

GitHub Codespaces is a cloud-basedin-browser development environment that comes with the appropriate setup tocontribute to Matplotlib.

  1. Open codespaces on your fork by clicking on the greenCodebutton on the GitHub web interface and selecting theCodespaces tab.

  2. Next, click on "Open codespaces on <your branch name>". You will beable to change branches later, so you can select the defaultmain branch.

  3. After the codespace is created, you will be taken to a new browsertab where you can use the terminal to activate a pre-defined condaenvironment calledmpl-dev:

    condaactivatempl-dev

Remember to activate thempl-dev environment whenever you start working onMatplotlib.

If you need to open a GUI window with Matplotlib output on Codespaces, ourconfiguration includes alight-weight Fluxbox-based desktop.You can use it by connecting to this desktop via your web browser. To do this:

  1. PressF1 orCtrl/Cmd+Shift+P and selectPorts:FocusonPortsView in the VSCode session to bring it intofocus. Open the ports view in your tool, select thenoVNC port, andclick the Globe icon.

  2. In the browser that appears, click the Connect button and enter the desktoppassword (vscode by default).

Check theGitHub instructionsfor more details on connecting to the desktop.

If you also built the documentation pages, you can view them using Codespaces.Use the "Extensions" icon in the activity bar to install the "Live Server"extension. Locate thedoc/build/html folder in the Explorer, right clickthe file you want to open and select "Open with Live Server."

Install Matplotlib in editable mode#

Install Matplotlib in editable mode from thematplotlib directory using thecommand

python-mpipinstall--verbose--no-build-isolation--editable".[dev]"

The 'editable/develop mode' builds everything and places links in your Python environmentso that Python will be able to import Matplotlib from your development source directory.This allows you to import your modified version of Matplotlib without having tore-install after changing a.py or compiled extension file.

When working on a branch that does not have Meson enabled, meaning it does nothavePR #26621 in its history (log), you will have to reinstall from sourceeach time you change any compiled extension code.

If the installation is not working, please consult thetroubleshooting guide.If the guide does not offer a solution, please reach out viachatoropen an issue.

Build options#

If you are working heavily with files that need to be compiled, you may want toinspect the compilation log. This can be enabled by setting the environmentvariableMESONPY_EDITABLE_VERBOSE or by setting theeditable-verboseconfig during installation

python-mpipinstall--no-build-isolation--config-settings=editable-verbose=true--editable.

For more information on installation and other configuration options, see theMeson Pythoneditable installs guide.

For a list of the other environment variables you can set before install, seeEnvironment variables.

Verify the Installation#

Run the following command to make sure you have correctly installed Matplotlib ineditable mode. The command should be run when the virtual environment is activated:

python-c"import matplotlib; print(matplotlib.__file__)"

This command should return :<matplotlib_local_repo>\lib\matplotlib\__init__.py

We encourage you to run tests and build docs to verify that the code installed correctlyand that the docs build cleanly, so that when you make code or document related changesyou are aware of the existing issues beforehand.

Install pre-commit hooks#

pre-commit hooks save time in the review process byidentifying issues with the code before a pull request is formally opened. Mosthooks can also aide in fixing the errors, and the checks should havecorrespondingdevelopment workflow andpull request guidelines. Hooks are configured in.pre-commit-config.yamland include checks for spelling and formatting, flake 8 conformity, accidentallycommitted files, import order, and incorrect branching.

Install pre-commit hooks

python-mpipinstallpre-commitpre-commitinstall

Hooks are run automatically after thegitcommit stage of theediting workflow. When a hook has found and fixed an error in afile, that file must bestaged and committed again.

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

pre-commitrun--all-files

To run a particular hook manually, runpre-commitrun with the hook id

pre-commitrun<hookid>--all-files

Please note that themypy pre-commit hook cannot check theType hintsfor new functions; instead the stubs for new functions are checked using thestubtestCI check and can be checked locally usingtox-estubtest.