Contributing guide#

You've discovered a bug or something else you want to changein Matplotlib — excellent!

You've worked out a way to fix it — even better!

You want to tell us about it — best of all!

Below, you can find a number of ways to contribute, and how to connect with theMatplotlib community.

Ways to contribute#

Do I really have something to contribute to Matplotlib?

100% yes! There are so many ways to contribute to our community. Take a lookat the following sections to learn more.

There are a few typical new contributor profiles:

  • You are a Matplotlib user, and you see a bug, a potential improvement, orsomething that annoys you, and you can fix it.

    You can search ourissue trackerfor an existing issue that describes your problem oropen a new issue to inform us of the problem you observed and discuss the best approachto fix it. If your contributions would not be captured on GitHub (social media,communication, educational content), you can also reach out to us ongitter,Discourse or attend any of ourcommunitymeetings.

  • You are not a regular Matplotlib user but a domain expert: you know aboutvisualization, 3D plotting, design, technical writing, statistics, or someother field where Matplotlib could be improved.

    Awesome — you have a focus on a specific application and domain and canstart there. In this case, maintainers can help you figure out the bestimplementation;open an issuein our issue tracker, and we'll be happy to discuss technical approaches.

    If you can implement the solution yourself, even better! Consider contributingthe change as apull request right away.

  • You are new to Matplotlib, both as a user and contributor, and want to startcontributing but have yet to develop a particular interest.

    Having some previous experience or relationship with the library can be veryhelpful when making open-source contributions. It helps you understand whythings are the way they are and how theyshould be. Having first-handexperience and context is valuable both for what you can bring to theconversation (and given the breadth of Matplotlib's usage, there is a goodchance it is a unique context in any given conversation) and make it easier tounderstand where other people are coming from.

    Understanding the entire codebase is a long-term project, and nobody expectsyou to do this right away. If you are determined to get started withMatplotlib and want to learn, going through the basic functionality,choosing something to focus on (3d, testing, documentation, animations, etc.)and gaining context on this area by reading the issues and pull requeststouching these subjects is a reasonable approach.

Code#

You want to implement a feature or fix a bug or help with maintenance - muchappreciated! Our library source code is found in:

  • Python library code:lib/

  • C-extension code:src/

  • Tests:lib/matplotlib/tests/

Because many people use and work on Matplotlib, we have guidelines for keepingour code consistent and mitigating the impact of changes.

Code is contributed through pull requests, so we recommend that you start atStart a pull request If you get stuck, please reach out on theContributor incubator

Documentation#

You, as an end-user of Matplotlib can make a valuable contribution because you canmore clearly see the potential for improvement than a core developer. For example,you can:

Our code is documented inline in the source code files inmatplotlib/lib.Our website structure mirrors our folder structure, meaning that a narrativedocument's URL roughly corresponds to its location in our folder structure:

using the library

  • galleries/plot_types/

  • users/getting_started/

  • galleries/user_explain/

  • galleries/tutorials/

  • galleries/examples/

  • doc/api/

information about the library

  • doc/install/

  • doc/project/

  • doc/devel/

  • doc/users/resources/index.rst

  • doc/users/faq.rst

Other documentation is generated from the following external sources:

Instructions and guidelines for contributing documentation are found in:

Documentation is contributed through pull requests, so we recommend that you startatStart a pull request. If that feels intimidating, we encourage you toopen an issue describing what improvements you would make. If you get stuck,please reach out on theContributor incubator

Triage#

We appreciate your help keeping theissue trackerorganized because it is our centralized location for feature requests,bug reports, tracking major projects, and discussing priorities. Some examples of whatwe mean by triage are:

  • labeling issues and pull requests

  • verifying bug reports

  • debugging and resolving issues

  • linking to related issues, discussion, and external work

Our triage process is discussed in detail inBug triaging and issue curation.

If you have any questions about the process, please reach out on theContributor incubator

Community#

Matplotlib's community is built by its members, if you would like to help outsee ourCommunity management guide.

It helps us if you spread the word: reference the project from your blogand articles or link to it from your website!

If Matplotlib contributes to a project that leads to a scientific publication,please cite us following theCiting Matplotlib guidelines.

If you have developed an extension to Matplotlib, please consider adding it to ourthird party package list.

Restrictions on Generative AI Usage#

We expect authentic engagement in our community.

  • Do not post output from Large Language Models or similar generative AI ascomments on GitHub or our discourse server, as such comments tend to beformulaic and low content.

  • If you use generative AI tools as an aid in developing code or documentationchanges, ensure that you fully understand the proposed changes and canexplain why they are the correct approach.

Make sure you have added value based on your personal competency to yourcontributions. Just taking some input, feeding it to an AI and posting theresult is not of value to the project. To preserve precious core developercapacity, we reserve the right to rigorously reject seemingly AI generatedlow-value contributions.

New contributors#

Everyone comes to the project from a different place — in terms of experienceand interest — so there is no one-size-fits-all path to getting involved. Werecommend looking at existing issue or pull request discussions, and followingthe conversations during pull request reviews to get context. Or you candeep-dive into a subset of the code-base to understand what is going on.

New contributors meeting#

Once a month, we host a meeting to discuss topics that interest newcontributors. Anyone can attend, present, or sit in and listen to the call.Among our attendees are fellow new contributors, as well as maintainers, andveteran contributors, who are keen to support onboarding of new folks andshare their experience. You can find our community calendar link at theScientific Python website, andyou can browse previous meeting notes onGitHub.We recommend joining the meeting to clarify any doubts, or lingeringquestions you might have, and to get to know a few of the people behind theGitHub handles 😉. You can reach out to us ongitter for any clarifications orsuggestions. We ❤ feedback!

Contributor incubator#

The incubator is our non-public communication channel for new contributors. Itis a privategitter (chat) room moderated by core Matplotlib developers whereyou can get guidance and support for your first few PRs. It's a place where youcan ask questions about anything: how to use git, GitHub, how our PR reviewprocess works, technical questions about the code, what makes for gooddocumentation or a blog post, how to get involved in community work, or get a"pre-review" on your PR.

To join, please go to our publiccommunity gitter channel, and ask to be added to#incubator. One of our core developers will see your message and will add you.

Good first issues#

While any contributions are welcome, we have marked some issues asparticularly suited for new contributors by the labelgood first issue. Theseare well documented issues, that do not require a deep understanding of theinternals of Matplotlib. The issues may additionally be tagged with adifficulty.Difficulty:Easy is suited for people with little Pythonexperience.Difficulty:Medium andDifficulty:Hard require moreprogramming experience. This could be for a variety of reasons, among them,though not necessarily all at the same time:

  • The issue is in areas of the code base which have more interdependencies,or legacy code.

  • It has less clearly defined tasks, which require some independentexploration, making suggestions, or follow-up discussions to clarify a goodpath to resolve the issue.

  • It involves Python features such as decorators and context managers, whichhave subtleties due to our implementation decisions.

First contributions#

If this is your first open source contribution, or your first time contributing to Matplotlib,and you need help or guidance finding a good first issue, look no further. This section willguide you through each step:

  1. Navigate to theissues page.

  2. Filter labels with"Difficulty: Easy"&"Good first Issue" (optional).

  3. Click on an issue you would like to work on, and check to see if the issue has a pull request opened to resolve it.

    • A good way to judge if you chose a suitable issue is by asking yourself, "Can I independently submit a PR in 1-2 weeks?"

  4. Check existing pull requests (e.g.,PR #28476) and filter by the issue number to make sure the issue is not in progress:

    • If the issue has a pull request (is in progress), tag the user working on the issue, and ask to collaborate (optional).

    • If there is no pull request,create a new pull request.

  5. Please familiarize yourself with the pull request template (see below),and ensure you understand/are able to complete the template when you open your pull request.Additional information can be found in thepull request guidelines.

Pull request template
<!--Thank you so much for your PR!  To help us review your contribution, please checkout the development guide https://matplotlib.org/devdocs/devel/index.html-->## PR summary<!-- Please describe the pull request, using the questions below as guidance, and link to any relevant issues and PRs:-Why is this change necessary?-What problem does it solve?-What is the reasoning for this implementation?Additionally, please summarize the changes in the title, for example "Raise ValueError onnon-numeric input to set_xlim" and avoid non-descriptive titles such as "Addressesissue#8576".If possible, please provide a minimum self-contained example.  If you have usedgenerative AI as an aid in preparing this PR, seehttps://matplotlib.org/devdocs/devel/contribute.html#restrictions-on-generative-ai-usage-->## PR checklist<!-- Please mark any checkboxes that do not apply to this PR as [N/A].-->- [ ] "closes#0000" is in the body of the PR description to [link the related issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)- [ ] new and changed code is [tested](https://matplotlib.org/devdocs/devel/testing.html)- [ ]*Plotting related* features are demonstrated in an [example](https://matplotlib.org/devdocs/devel/document.html#write-examples-and-tutorials)- [ ]*New Features* and*API Changes* are noted with a [directive and release note](https://matplotlib.org/devdocs/devel/api_changes.html#announce-changes-deprecations-and-new-features)- [ ] Documentation complies with [general](https://matplotlib.org/devdocs/devel/document.html#write-rest-pages) and [docstring](https://matplotlib.org/devdocs/devel/document.html#write-docstrings) guidelines<!--We understand that PRs can sometimes be overwhelming, especially as thereviews start coming in.  Please let us know if the reviews are unclear orthe recommended next step seems overly demanding, if you would like help inaddressing a reviewer's comments, or if you have been waiting too long to hearback on your PR.-->

Get connected#

When in doubt, we recommend going together! Get connected with our community ofactive contributors, many of whom felt just like you when they started out andare happy to welcome you and support you as you get to know how we work, andwhere things are. You can reach out on any of ourOfficial communication channels.For development questions we recommend reaching out on our developmentgitterchat room and for community questions reach out atcommunity gitter.

Choose an issue#

In general, the Matplotlib project does not assign issues. Issues are"assigned" or "claimed" by opening a PR; there is no other assignmentmechanism. If you have opened such a PR, please comment on the issue thread toavoid duplication of work. Please check if there is an existing PR for theissue you are addressing. If there is, try to work with the author bysubmitting reviews of their code or commenting on the PR rather than openinga new PR; duplicate PRs are subject to being closed. However, if the existingPR is an outline, unlikely to work, or stalled, and the original author isunresponsive, feel free to open a new PR referencing the old one.

Start a pull request#

The preferred way to contribute to Matplotlib is to fork themainrepository on GitHub,then submit a "pull request" (PR). To work on a a pull request:

  1. First set up a development environment, either by cloning a copy of theMatplotlib repository to your own computer or by using Github codespaces, byfollowing the instructions inSetting up Matplotlib for development

  2. Then start solving the issue, following the guidance indevelopment workflow

  3. As part of verifying your changes check that your contribution meetsthepull request guidelinesand thenopen a pull request.

  4. Finally follow up with maintainers on the PR if waiting more than a few days forfeedback.Update the pull request as needed.

If you have questions of any sort, reach out on theContributor incubator and jointheNew contributors meeting.