Setting up Matplotlib for development#
To set up Matplotlib for development follow these steps:
Matplotlib is hosted at matplotlib/matplotlib.git. If you
plan on solving issues or submitting 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.
Now that your fork of the repository lives under your GitHub username, you can
retrieve the most recent version of the source code with one of the following
<your-username> with your GitHub username):
git clone https://github.com/<your-username>/matplotlib.git
This will place the sources in a directory
matplotlib below your
current working directory and set the remote name
origin to point to your
fork. Change into this directory before continuing:
Now set the remote name
upstream to point to the Matplotlib main repository:
git remote add upstream https://github.com/matplotlib/matplotlib.git
You can now use
upstream to retrieve the most current snapshot of the source
code, as described in Development workflow.
For more information on
You should set up a dedicated environment to decouple your Matplotlib development from other Python and Matplotlib installations on your system.
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
For a discussion of the technical reasons, see PEP-394.
Install the Python dependencies with
pip install -r requirements/dev/dev-requirements.txt
Remember to activate the environment whenever you start working on Matplotlib.
Most Python dependencies will be installed when setting up the environment but non-Python dependencies like C++ compilers, LaTeX, and other system applications must be installed separately.
Install Matplotlib in editable mode from the
matplotlib directory using the
python -m pip install --verbose --no-build-isolation --editable .[dev]
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 having to
re-install after changing a
.py or compiled extension file.
When working on a branch that does not have Meson enabled, meaning it does not have PR #26621 in its history (log), you will have to reinstall from source each time you change any compiled extension code.
If you are working heavily with files that need to be compiled, you may want to
inspect the compilation log. This can be enabled by setting the environment
MESONPY_EDITABLE_VERBOSE or by setting the
config during installation
python -m pip install --no-build-isolation --config-settings=editable-verbose=true --editable .
For more information on installation and other configuration options, see the Meson Python editable installs guide.
For a list of the other environment variables you can set before install, see Environment variables.
Run the following command to make sure you have correctly installed Matplotlib in editable mode. The command should be run when the virtual environment is activated:
python -c "import matplotlib; print(matplotlib.__file__)"
This command should return :
We encourage you to run tests and build docs to verify that the code installed correctly and that the docs build cleanly, so that when you make code or document related changes you are aware of the existing issues beforehand.
pre-commit hooks save time in the review process by identifying issues with the code before a pull request is formally opened. Most hooks can also aide in fixing the errors, and the checks should have corresponding development workflow and pull request guidelines. Hooks are configured in .pre-commit-config.yaml and include checks for spelling and formatting, flake 8 conformity, accidentally committed files, import order, and incorrect branching.
Install pre-commit hooks
python -m pip install pre-commit pre-commit install
Hooks are run automatically after the
git commit stage of the
editing workflow. When a hook has found and fixed an error in a
file, that file must be staged and committed again.
Hooks can also be run manually. All the hooks can be run, in order as
.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