How to Contribute to Matplotlib on GitHub

So you’ve been using Matplotlib for a while and want to give back to the project. Maybe you spotted a bug, have an idea for an improvement, or just want to dive into open-source development for the first time.

Whatever the reason, contributing to Matplotlib is very doable, and this guide walks you through the entire process from forking the repo to submitting your first pull request.

Who Can Contribute?

Before I get into the technical steps, I want to address something that trips up a lot of people: “Am I experienced enough to contribute?”

The answer is yes — 100%. The Matplotlib maintainers actively welcome contributions at all levels. There are typically three kinds of contributors:

• You’re a regular Matplotlib user who spotted a bug, a confusing docstring, or a missing example. This is honestly the best place to start — you already have context.
• You’re a domain expert — maybe in statistics, 3D plotting, design, or technical writing — and you can see places where things could be better.
• You’re new to Matplotlib entirely and want to learn by contributing. That works too — start with the “good first issues” list (more on that below).

Nobody expects you to understand the entire codebase on day one.

Check out: Create a Matplotlib Boxplot for Time Series Data in Python

What Can You Contribute?

Contributing doesn’t have to mean writing complex Python code. Here are the different ways you can help:

Code contributions:

• Fix a reported bug
• Implement a feature that’s been requested in the issue tracker
• Add or improve test coverage
• Help with maintenance and code cleanup

Documentation contributions:

• Fix a typo in the docs
• Clarify a docstring that’s confusing
• Write or update a tutorial or example
• Improve the getting started guide

Triage contributions:

• Label issues and pull requests
• Verify and reproduce bug reports
• Link related issues together
• Help debug problems reported by other users

Community contributions:

• Write blog posts or articles about Matplotlib
• Share the project on social media
• Attend the monthly new contributors meeting

If you’re just starting, documentation fixes are a fantastic entry point. They follow the same PR workflow as code changes, but with a much lower barrier.

What You Need Before Starting

Make sure you have these installed on your machine before diving in:

• Python 3.9 or higher — check with python –version
• Git — check with git –version. If not installed, download from git-scm.com
• A GitHub account — free to create at github.com
• A text editor or IDE (VS Code, PyCharm, etc.)

You’ll also want a basic comfort level with Git commands (clone, add, commit, push, branch). If you’re new to Git, I’d recommend spending 30 minutes on the GitHub “Hello World” guide before going further — it’ll make everything below much smoother.

Step 1 — Fork the Matplotlib Repository

First, you need your own copy of the Matplotlib codebase on GitHub. This is called a “fork.”

1. Go to github.com/matplotlib/matplotlib
2. Click the Fork button near the top right of the page
3. Under “Owner,” make sure your GitHub username is selected
4. Click Create fork

GitHub will create a full copy of the repository under your account — something like github.com/your-username/matplotlib. This is where all your changes will live before you propose them to the main project.

Step 2 — Clone Your Fork Locally

Now bring that fork down to your local machine:

Using HTTPS:

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

Using SSH (recommended if you use 2-factor auth):

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

Then move into the directory:

cd matplotlib

Now add the main Matplotlib repository as a remote called upstream. You’ll use this to pull in the latest changes from the main project:

git remote add upstream https://github.com/matplotlib/matplotlib.git

Verify your remotes are set up correctly:

git remote -v

You should see something like:

origin    https://github.com/your-username/matplotlib.git (fetch)
origin    https://github.com/your-username/matplotlib.git (push)
upstream  https://github.com/matplotlib/matplotlib.git (fetch)
upstream  https://github.com/matplotlib/matplotlib.git (push)

Read: Plot Multiple Bar Charts with Time Series in Matplotlib

Step 3 — Set Up a Dedicated Development Environment

Never work inside your system Python or your day-to-day Python environment when doing development work. Always create a dedicated environment for the Matplotlib project so it doesn’t interfere with anything else.

You have two options: venv or conda.

Option A: Use venv

Create the environment:

python -m venv mpl-dev-env

Activate it:

On macOS/Linux:

source mpl-dev-env/bin/activate

On Windows (Command Prompt):

mpl-dev-env\Scripts\activate.bat

On Windows (PowerShell):

mpl-dev-env\Scripts\Activate.ps1

Install the development dependencies:

pip install -r requirements/dev/dev-requirements.txt

Option B: Use conda

If you’re on Anaconda or Miniconda, this is the easiest path — it sets everything up in one command:

conda env create -f environment.yml
conda activate mpl-dev

Important: Remember to activate your development environment every time you open a new terminal and start working on Matplotlib. I’ve forgotten this more times than I’d like to admit — it always causes confusion.

Step 4 — Install Matplotlib in Editable Mode

This is the step that makes developer setup different from a regular installation. “Editable mode” means Python links directly to your local source files, so any changes you make to the code are immediately reflected when you import Matplotlib — no reinstalling required.

From inside the matplotlib directory (with your environment activated), run:

python -m pip install --verbose --no-build-isolation --editable ".[dev]"

This builds Matplotlib from source and installs it in editable mode along with all developer tools.

Verify it worked:

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

You should see a path pointing to your local cloned repo — something like:

/path/to/matplotlib/lib/matplotlib/__init__.py

If it points to your local repo, you’re all set. If it points somewhere else like /usr/local/lib/…, the editable install didn’t take — check that your dev environment is activated.

Check out: Matplotlib 2D Color Surface Plots

Step 5 — Install Pre-commit Hooks

Pre-commit hooks run automatic checks on your code before every git commit. They catch things like formatting issues, spelling errors, import order problems, and style inconsistencies — saving you from reviewer feedback on basic issues.

Install pre-commit and set up the hooks:

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

You can see the output in the screenshot below.

After this, the hooks run automatically every time you do git commit. You can also run them manually across the entire codebase:

pre-commit run --all-files

Or run a specific hook:

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

If a hook finds and fixes a file, you’ll need to stage and commit that file again before the commit goes through.

I know pre-commit can feel like friction at first, but it genuinely saves time. It’s much faster to catch a style issue locally than to have it flagged in PR review.

Step 6 — Find an Issue to Work On

With your environment ready, the next step is picking something to work on.

For first-time contributors:

Go to github.com/matplotlib/matplotlib/issues and filter by the label good first issue. These are specifically selected to be approachable without needing a deep understanding of the codebase.

You can also filter by Difficulty: Easy for issues suited to folks with less Python experience, or Difficulty: Medium / Difficulty: Hard if you’re comfortable going deeper.

A practical gut-check before picking an issue: ask yourself — “Can I independently submit a pull request for this in 1–2 weeks?” If the answer is yes, it’s a good fit for where you are right now.

Before starting work on any issue:

• Read through the issue thread carefully — context matters a lot
• Check if there’s already an open PR for it (filter PRs by the issue number)
• If someone’s already working on it, consider collaborating with them rather than duplicating effort
• Leave a comment on the issue saying you’re planning to work on it

Note: Matplotlib doesn’t “assign” issues — you claim an issue by opening a PR for it.

Step 7 — Create a Branch and Make Your Changes

Never work directly on the main branch. Always create a new branch for each fix or feature you work on:

git checkout -b fix/your-descriptive-branch-name

Use a meaningful name that reflects what the branch does. For example:

• fix/bar-chart-negative-values
• docs/clarify-subplots-docstring
• feature/add-step-line-style

Keep your branch up to date with the main project:

Before you start writing code, and periodically as you work, pull in the latest changes from upstream:

git fetch upstream
git rebase upstream/main

This keeps your branch current and reduces merge conflicts when you submit your PR.

Make your changes, then stage and commit them:

git add path/to/changed-file.py
git commit -m "Fix: descriptive message about what changed and why"

Write commit messages in the imperative mood — “Fix incorrect axis scaling” rather than “Fixed incorrect axis scaling.”

Step 8 — Write and Run Tests

Any code change should be accompanied by tests. Matplotlib’s tests live in:

lib/matplotlib/tests/

Running the full test suite:

python -m pytest lib/matplotlib/tests/ -v

Running tests for a specific module:

python -m pytest lib/matplotlib/tests/test_axes.py -v

Running a single test:

python -m pytest lib/matplotlib/tests/test_axes.py::test_function_name -v

Running the full suite takes a while — running only the tests relevant to the file you changed is usually enough during development.

If you’re adding a new feature or fixing a bug, add a test in the relevant test file that covers your change. A PR without tests for new behavior will likely get review comments asking you to add them.

Read: How to Set Axis Limits in Matplotlib 3D Plots

Step 9 — Open a Pull Request

Once your changes are ready and tests pass:

Push your branch to your GitHub fork:

git push origin fix/your-descriptive-branch-name

Then open the PR on GitHub:

1. Go to github.com/your-username/matplotlib
2. GitHub will usually show a banner saying your branch was recently pushed — click “Compare & pull request”
3. Or navigate to the Pull requests tab and click New pull request

Fill out the PR template carefully. The Matplotlib PR template asks:

• Why is this change necessary?
• What problem does it solve?
• What is the reasoning for this implementation?

Make sure the PR description includes closes #ISSUE_NUMBER — this automatically links and closes the issue when the PR is merged.

The PR checklist includes:

• New and changed code is tested
• Plotting-related features have a gallery example
• New features have a changelog entry with a release note
• Documentation follows style guidelines

Once submitted, a maintainer will review your PR. Don’t be discouraged if you get feedback asking for changes — it happens to everyone, including veteran contributors. It’s part of the process.

If you haven’t heard back in a few days, it’s completely fine to leave a polite follow-up comment on the PR.

Use GitHub Codespaces (No Local Setup Needed)

If you want to make a quick, one-off change without going through the full local setup, GitHub Codespaces is a solid option. It’s a cloud-based VS Code environment that comes pre-configured for Matplotlib development.

To open it:

1. Go to the Matplotlib repository (or your fork)
2. Click the green Code button
3. Select the Codespaces tab
4. Click Create codespace on main

The environment spins up in your browser with everything already installed. Just make your changes, commit, and push. Note that Codespaces has monthly free usage limits, so for regular contributions, the local setup is worth the initial investment.

Connect With the Matplotlib Community

Contributing to open source is much easier when you’re connected to other contributors. Here’s where the Matplotlib community lives:

• Contributor Incubator: A private channel for new contributors moderated by core developers. You can ask anything here — git questions, PR feedback, technical questions. To join, go to the Matplotlib Discourse and ask to be added to #incubator.
• Monthly new contributors meeting: Held once a month, open to anyone. Core maintainers and veteran contributors attend to answer questions and support newcomers. The calendar link is on the Matplotlib community page.
• GitHub Discussions: For broader questions about the project direction, design decisions, and feature discussions.
• Issue tracker: The central place for bug reports, feature requests, and project tracking.

I’d recommend attending at least one new contributors meeting before you dive into writing code — you’ll get a real feel for how things work and who to reach out to.

Common Questions

You may read:

• Set Axis Limits for All Subplots in Matplotlib
• Set Axis Range in Matplotlib imshow
• Set the Secondary Axis Range in Matplotlib
• How to Set Axis Lower Limit in Matplotlib

Bijay Kumar

I am Bijay Kumar, a Microsoft MVP in SharePoint. Apart from SharePoint, I started working on Python, Machine learning, and artificial intelligence for the last 5 years. During this time I got expertise in various Python libraries also like Tkinter, Pandas, NumPy, Turtle, Django, Matplotlib, Tensorflow, Scipy, Scikit-Learn, etc… for various clients in the United States, Canada, the United Kingdom, Australia, New Zealand, etc. Check out my profile.

enjoysharepoint.com/