This project is a community effort, and everyone is welcome to contribute. Everyone within the community is expected to abide by our code of conduct.
The project is hosted on matplotlib/matplotlib
Do I really have something to contribute to Matplotlib?#
100% yes. There are so many ways to contribute to our community.
When in doubt, we recommend going together! Get connected with our community of active contributors, many of whom felt just like you when they started out and are happy to welcome you and support you as you get to know how we work, and where things are. Take a look at the next sections to learn more.
The incubator is our non-public communication channel for new contributors. It is a private gitter room moderated by core Matplotlib developers where you can get guidance and support for your first few PRs. It's a place you can ask questions about anything: how to use git, github, how our PR review process works, technical questions about the code, what makes for good documentation or a blog post, how to get involved in community work, or get "pre-review" on your PR.
To join, please go to our public gitter community channel, and ask to be added to '#incubator'. One of our core developers will see your message and will add you.
New Contributors meeting#
Once a month, we host a meeting to discuss topics that interest new contributors. Anyone can attend, present, or sit in and listen to the call. Among our attendees are fellow new contributors, as well as maintainers, and veteran contributors, who are keen to support onboarding of new folks and share their experience. You can find our community calendar link at the Scientific Python website, and you can browse previous meeting notes on github. We recommend joining the meeting to clarify any doubts, or lingering questions you might have, and to get to know a few of the people behind the GitHub handles 😉. You can reach out to @noatamir on gitter for any clarifications or suggestions. We <3 feedback!
Issues for new contributors#
While any contributions are welcome, we have marked some issues as
particularly suited for new contributors by the label good first issue. These
are well documented issues, that do not require a deep understanding of the
internals of Matplotlib. The issues may additionally be tagged with a
Difficulty: Easy is suited for people with little Python
Difficulty: Medium and
Difficulty: Hard require more
programming 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 independent exploration, making suggestions, or follow-up discussions to clarify a good path to resolve the issue.
It involves Python features such as decorators and context managers, which have subtleties due to our implementation decisions.
In general, the Matplotlib project does not assign issues. Issues are "assigned" or "claimed" by opening a PR; there is no other assignment mechanism. If you have opened such a PR, please comment on the issue thread to avoid duplication of work. Please check if there is an existing PR for the issue you are addressing. If there is, try to work with the author by submitting reviews of their code or commenting on the PR rather than opening a new PR; duplicate PRs are subject to being closed. However, if the existing PR is an outline, unlikely to work, or stalled, and the original author is unresponsive, feel free to open a new PR referencing the old one.
Submitting a bug report#
If you find a bug in the code or documentation, do not hesitate to submit a ticket to the Issue Tracker. You are also welcome to post feature requests or pull requests.
If you are reporting a bug, please do your best to include the following:
A short, top-level summary of the bug. In most cases, this should be 1-2 sentences.
A short, self-contained code snippet to reproduce the bug, ideally allowing a simple copy and paste to reproduce. Please do your best to reduce the code snippet to the minimum required.
The actual outcome of the code snippet.
The expected outcome of the code snippet.
The Matplotlib version, Python version and platform that you are using. You can grab the version with the following commands:
>>> import matplotlib >>> matplotlib.__version__ '3.4.1' >>> import platform >>> platform.python_version() '3.9.2'
We have preloaded the issue creation page with a Markdown form that you can use to organize this information.
Thank you for your help in keeping bug reports complete, targeted and descriptive.
Requesting a new feature#
Please post feature requests to the Issue Tracker.
The Matplotlib developers will give feedback on the feature proposal. Since Matplotlib is an open source project with limited resources, we encourage users to then also participate in the implementation.
How to contribute#
The preferred way to contribute to Matplotlib is to fork the main repository on GitHub, then submit a "pull request" (PR).
A brief overview is:
Create an account on GitHub if you do not already have one.
Fork the project repository: click on the 'Fork' button near the top of the page. This creates a copy of the code under your account on the GitHub server.
Clone this copy to your local disk:
git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
Enter the directory and install the local version of Matplotlib. See Setting up Matplotlib for development for instructions
Create a branch to hold your changes:
git checkout -b my-feature origin/main
and start making changes. Never work in the
Work on this copy, on your computer, using Git to do the version control. When you're done editing e.g.,
git add lib/matplotlib/collections.py git commit
to record your changes in Git, then push them to GitHub with:
git push -u origin my-feature
Finally, go to the web page of your fork of the Matplotlib repo, and click 'Pull request' to send your changes to the maintainers for review.
Contributing pull requests#
It is recommended to check that your contribution complies with the following rules before submitting a pull request:
If your pull request addresses an issue, please use the title to describe the issue and mention the issue number in the pull request description to ensure that a link is created to the original issue.
All public methods should have informative docstrings with sample usage when appropriate. Use the numpy docstring standard.
python -m pip install flake8 flake8 /path/to/module.py
or your editor may provide integration with it. Note that Matplotlib intentionally does not use the black auto-formatter (1), in particular due to its unability to understand the semantics of mathematical expressions (2, 3).
Each high-level plotting function should have a simple example in the
Examplesection of the docstring. This should be as simple as possible to demonstrate the method. More complex examples should go in the
Changes (both new features and bugfixes) should have good test coverage. See Testing for more details.
Import the following modules using the standard scipy conventions:
import numpy as np import numpy.ma as ma import matplotlib as mpl import matplotlib.pyplot as plt import matplotlib.cbook as cbook import matplotlib.patches as mpatches
In general, Matplotlib modules should not import
from matplotlib import rcParams, but rather access it as
mpl.rcParams. This is because some modules are imported very early, before the
rcParamssingleton is constructed.
If your change is a major new feature, add an entry to the
What's newsection by adding a new file in
doc/users/next_whats_new/README.rstfor more information).
If you change the API in a backward-incompatible way, please document it in
doc/api/next_api_changes/behavior, by adding a new file with the naming convention
99999-ABC.rstwhere the pull request number is followed by the contributor's initials. (see
doc/api/api_changes.rstfor more information)
See below for additional points about Keyword argument processing, if applicable for your pull request.
The current state of the Matplotlib code base is not compliant with all of those guidelines, but we expect that enforcing those constraints on all new contributions will move the overall code base quality in the right direction.
You as an end-user of Matplotlib can make a valuable contribution because you more clearly see the potential for improvement than a core developer. For example, you can:
Fix a typo
Clarify a docstring
Write or update an example plot
Write or update a comprehensive tutorial
The documentation source files live in the same GitHub repository as the code. Contributions are proposed and accepted through the pull request process. For details see How to contribute.
If you have trouble getting started, you may instead open an issue describing the intended improvement.
Other ways to contribute#
It also helps us if you spread the word: reference the project from your blog and articles or link to it from your website! If Matplotlib contributes to a project that leads to a scientific publication, please follow the Citing Matplotlib guidelines.
API consistency and stability are of great value. Therefore, API changes (e.g. signature changes, behavior changes, removals) will only be conducted if the added benefit is worth the user effort for adapting.
Because we are a visualization library our primary output is the final visualization the user sees. Thus it is our long standing policy that the appearance of the figure is part of the API and any changes, either semantic or esthetic, will be treated as a backwards-incompatible API change.
API changes in Matplotlib have to be performed following the deprecation process below, except in very rare circumstances as deemed necessary by the development team. This ensures that users are notified before the change will take effect and thus prevents unexpected breaking of code.
Deprecations are targeted at the next point.release (e.g. 3.x)
Deprecated API is generally removed two point-releases after introduction of the deprecation. Longer deprecations can be imposed by core developers on a case-by-case basis to give more time for the transition
The old API must remain fully functional during the deprecation period
If alternatives to the deprecated API exist, they should be available during the deprecation period
If in doubt, decisions about API changes are finally made by the API consistency lead developer
Announce the deprecation in a new file
99999is the pull request number and
ABCare the contributor's initials.
If possible, issue a
MatplotlibDeprecationWarningwhen the deprecated API is used. There are a number of helper tools for this:
_api.warn_deprecated()for general deprecation warnings
Use the decorator
@_api.deprecatedto deprecate classes, functions, methods, or properties
To warn on changes of the function signature, use the decorators
All these helpers take a first parameter since, which should be set to the next point release, e.g. "3.x".
You can use standard rst cross references in alternative.
Announce the API changes in a new file
99999is the pull request number and
ABCare the contributor's initials, and
[kind]is one of the folders
doc/api/next_api_changes/README.rstfor more information. For the content, you can usually copy the deprecation notice and adapt it slightly.
Change the code functionality and remove any related deprecation warnings.
Adding new API#
Every new function, parameter and attribute that is not explicitly marked as private (i.e., starts with an underscore) becomes part of Matplotlib's public API. As discussed above, changing the existing API is cumbersome. Therefore, take particular care when adding new API:
Mark helper functions and internal attributes as private by prefixing them with an underscore.
Carefully think about good names for your functions and variables.
Try to adopt patterns and naming conventions from existing parts of the Matplotlib API.
Consider making as many arguments keyword-only as possible. See also API Evolution the Right Way -- Add Parameters Compatibly.
New modules and files: installation#
If you have added new files or directories, or reorganized existing ones, make sure the new files are included in the match patterns in in package_data in
Extensions may be written in C or C++.
Code style should conform to PEP7 (understanding that PEP7 doesn't address C++, but most of its admonitions still apply).
Python/C interface code should be kept separate from the core C/C++ code. The interface code should be named
Header file documentation (aka docstrings) should be in Numpydoc format. We don't plan on using automated tools for these docstrings, and the Numpydoc format is well understood in the scientific Python community.
C/C++ code in the
extern/directory is vendored, and should be kept close to upstream whenever possible. It can be modified to fix bugs or implement new features only if the required changes cannot be made elsewhere in the codebase. In particular, avoid making style fixes to it.
Keyword argument processing#
Matplotlib makes extensive use of
**kwargs for pass-through customizations
from one function to another. A typical example is
text. The definition of
matplotlib.pyplot.text is a
simple pass-through to
# in pyplot.py def text(x, y, s, fontdict=None, **kwargs): return gca().text(x, y, s, fontdict=fontdict, **kwargs)
matplotlib.axes.Axes.text (simplified for illustration) just
kwargs on to
# in axes/_axes.py def text(self, x, y, s, fontdict=None, **kwargs): t = Text(x=x, y=y, text=s, **kwargs)
matplotlib.text.Text.__init__ (again, simplified)
just passes them on to the
# in text.py def __init__(self, x=0, y=0, text='', **kwargs): super().__init__() self.update(kwargs)
update does the work looking for methods named like
property is a keyword argument. i.e., no one
looks at the keywords, they just get passed through the API to the
artist constructor which looks for suitably named methods and calls
them with the value.
As a general rule, the use of
**kwargs should be reserved for
pass-through keyword arguments, as in the example above. If all the
keyword args are to be used in the function, and not passed
on, use the key/value keyword args in the function definition rather
In some cases, you may want to consume some keys in the local
function, and let others pass through. Instead of popping arguments to
**kwargs, specify them as keyword-only arguments to the local
function. This makes it obvious at a glance which arguments will be
consumed in the function. For example, in
local arguments and the rest are passed on as
Line2D() keyword arguments:
# in axes/_axes.py def plot(self, *args, scalex=True, scaley=True, **kwargs): lines =  for line in self._get_lines(*args, **kwargs): self.add_line(line) lines.append(line)
Using logging for debug messages#
Matplotlib uses the standard Python
logging library to write verbose
warnings, information, and debug messages. Please use it! In all those places
logging in your module, at the top of the module, you need to
import logging. Then calls in your code like:
_log = logging.getLogger(__name__) # right after the imports # code # more code _log.info('Here is some information') _log.debug('Here is some more detailed information')
will log to a logger named
If an end-user of Matplotlib sets up
logging to display at levels more
logging.WARNING in their code with the Matplotlib-provided
or manually with
import logging logging.basicConfig(level=logging.DEBUG) import matplotlib.pyplot as plt
Then they will receive messages like
DEBUG:matplotlib.backends:backend MacOSX version unknown DEBUG:matplotlib.yourmodulename:Here is some information DEBUG:matplotlib.yourmodulename:Here is some more detailed information
Which logging level to use?#
There are five levels at which you can emit messages.
logging.infois for information that the user may want to know if the program behaves oddly. They are not displayed by default. For instance, if an object isn't drawn because its position is
NaN, that can usually be ignored, but a mystified user could call
logging.basicConfig(level=logging.INFO)and get an error message that says why.
logging.debugis the least likely to be displayed, and hence can be the most verbose. "Expected" code paths (e.g., reporting normal intermediate steps of layouting or rendering) should only log at this level.
The logging tutorial suggests that the difference between
_api.warn_external (which uses
warnings.warn) is that
_api.warn_external should be used for things the user must change to stop
the warning (typically in the source), whereas
logging.warning can be more
persistent. Moreover, note that
_api.warn_external will by default only
emit a given warning once for each line of user code, whereas
logging.warning will display the message every time it is called.
warnings.warn displays the line of code that has the
call. This usually isn't more informative than the warning message itself.
Therefore, Matplotlib uses
_api.warn_external which uses
but goes up the stack and displays the first line of code outside of
Matplotlib. For example, for the module:
# in my_matplotlib_module.py import warnings def set_range(bottom, top): if bottom == top: warnings.warn('Attempting to set identical bottom==top')
running the script:
from matplotlib import my_matplotlib_module my_matplotlib_module.set_range(0, 0) # set range
UserWarning: Attempting to set identical bottom==top warnings.warn('Attempting to set identical bottom==top')
Modifying the module to use
from matplotlib import _api def set_range(bottom, top): if bottom == top: _api.warn_external('Attempting to set identical bottom==top')
and running the same script will display
UserWarning: Attempting to set identical bottom==top my_matplotlib_module.set_range(0, 0) # set range
We have hundreds of examples in subdirectories of
and these are automatically generated when the website is built to show up in
the examples section of the website.
Any sample data that the example uses should be kept small and
distributed with Matplotlib in the
lib/matplotlib/mpl-data/sample_data/ directory. Then in your
example code you can load it into a file handle with:
import matplotlib.cbook as cbook fh = cbook.get_sample_data('mydata.dat')