Matplotlib: A Working Guide to the Python Plotting Library

What Matplotlib Solves, and Who Reaches for It

The project describes itself as "a comprehensive library for creating static, animated, and interactive visualizations in Python." That sentence covers a wider range than most plotting tools attempt. The same library produces a PNG for a paper, an animated frame sequence, and a window you can pan and zoom in. The pyproject.toml classifiers point at the audience: Science/Research and Education, Development Status 5 - Production/Stable.

That breadth is the reason it keeps getting chosen. A researcher who needs a figure for a journal and a developer who needs a chart embedded in a Qt desktop application are both served by the same import. The repository topics list gtk, qt, tk and wx alongside data-science and data-visualization, which reflects that the GUI toolkits are first-class integration targets rather than afterthoughts.

It is not aimed at people who want a chart in three lines and no further control. The API surface is large, and the documentation is correspondingly large. If your requirement is a quick bar chart in a web page, the effort of learning Matplotlib's layout model is not obviously repaid.

The pyplot State Machine Versus the Object-Oriented API

The mechanism most users meet first is pyplot, a stateful interface that keeps track of the current figure and current axes and draws into them. You call plotting functions, and they act on whatever the current axes happen to be. This is convenient in a notebook cell and confusing in a function that creates several figures.

The alternative is the object-oriented API, where you construct a Figure and one or more Axes explicitly and call methods on those objects. The README does not walk through this distinction, but it is visible in the repository layout: the library lives under lib/, the examples under galleries/, and the documentation under doc/. The recommended entry point for questions is the Discourse forum, which the README calls "the discussion forum for general questions and discussions and our recommended starting point."

In practice the two styles mix, and that mixing is the source of most confusion. A function that receives an Axes object and also calls a pyplot function will draw somewhere the caller did not expect. The rule that experienced users follow is to use pyplot only at the top level of a script or notebook and to pass Axes objects into everything below it.

Installing Matplotlib and Drawing a First Figure

The README does not inline install commands. It points to the install documentation, which is generated from /doc/install/index.rst. The package is published on PyPI and on conda-forge, and the badges at the top of the README link to both. The install documentation is the authoritative source for the exact commands, and this article does not reproduce them because they are not given in the README or in the repository files quoted here.

What the repository does state is the dependency set, declared in pyproject.toml: contourpy >= 1.2.1, cycler >= 0.12.0, fonttools >= 4.28.2, kiwisolver >= 1.3.1, numpy >= 2.0, packaging >= 20.0, pillow >= 9, pyparsing >= 3, and python-dateutil >= 2.7. The file also sets requires-python = ">=3.12", with classifiers for Python 3.12, 3.13 and 3.14. The numpy floor of 2.0 is the constraint most likely to collide with an older environment.

That dependency list is the practical thing to check before installing. If your environment pins numpy below 2.0, or runs an interpreter older than 3.12, the package will not resolve, and no amount of backend configuration will fix it. The pyproject.toml comment block notes that the dependency list must also be kept in sync with matplotlib._check_versions() in lib/matplotlib/__init__.py, ci/minver-requirements.txt, doc/install/dependencies.rst and environment.yml, which tells you the project treats the minimum versions as a contract rather than a suggestion.

Where Matplotlib Is the Wrong Tool

The strongest limitation is interactive, browser-native output. Matplotlib can render interactive figures, and it can be embedded in web application servers, but it is not a JavaScript charting library and does not produce the kind of DOM-based, hover-driven chart that a web front end expects. Reaching for it there means either exporting static images or adding a bridge layer.

The second limitation is statistical grammar. Matplotlib gives you primitives: lines, markers, patches, collections. It does not give you a declarative mapping from a dataframe column to an aesthetic. If your work is exploratory analysis over tidy data, you will write more code than you would with a library built around that model.

The third is API churn. The project uses EffVer versioning, indicated by the badge in the README, and the version history shows the pattern: v3.11.0 on 2026-06-12, v3.11.1 on 2026-07-18, v3.11.2 on 2026-09-11. Patch releases arrive quickly. Code that reaches into private attributes or relies on default colormap behaviour tends to need attention across minor versions.

How Matplotlib Differs from Plotly and Seaborn

Plotly takes the opposite architectural bet: figures are serialized to JSON and rendered by JavaScript, so interactivity and browser embedding come for free and static export is the derived case. Matplotlib renders through backends, with an Agg rasterizer for file output and toolkit-specific backends for on-screen display. If your deliverable is a web page with tooltips, Plotly starts closer to the finish line. If your deliverable is a vector PDF for print, Matplotlib starts closer.

Seaborn is not a competitor so much as a layer. It targets statistical graphics and builds on top of Matplotlib, so the underlying rendering is the same. The difference in approach is the interface: Seaborn accepts a dataframe and a mapping of variables to roles, while Matplotlib accepts arrays and explicit drawing calls. Choosing Seaborn does not remove Matplotlib from your dependency tree; choosing Matplotlib does not prevent you from importing Seaborn for specific plots.

The practical split is that Matplotlib is the substrate. Libraries that need to draw in Python frequently draw through it, which is why it appears in so many dependency lists.

Maintenance, Licence and Upgrade Cost

The repository is not archived, and the last push was on 2026-09-19, two days before the date used for this assessment. Release cadence is steady: v3.11.0, v3.11.1 and v3.11.2 landed between June and September 2026.

Licensing is stated in two places that do not say quite the same thing. The pyproject.toml declares license = { file = "LICENSE/LICENSE" } and carries the classifier "License :: OSI Approved :: Python Software Foundation License". The repository has a LICENSE/ directory rather than a single file. Anyone redistributing Matplotlib, or bundling it into a product with its own licence terms, should read LICENSE/LICENSE directly rather than relying on the classifier string. This is not legal advice, and the classifier and the file are the two primary sources to reconcile.

Upgrade cost is mostly borne by code that depends on defaults. The dependency floor on numpy >= 2.0 and the Python floor of >=3.12 mean an upgrade can force an interpreter or numpy upgrade in the same step. The project maintains a contributing guide and a code of conduct, and the README explicitly welcomes pull requests, so the maintenance burden is shared rather than vendor-held. NumFOCUS is listed as the fiscal sponsor.

Editorial conclusion

Adopt Matplotlib when you need publication-quality static figures from Python and want a single library that works in scripts, notebooks, web servers and GUI toolkits. Do not adopt it for browser-native interactive dashboards or for grammar-of-graphics statistical plots; those are different tools with different APIs. Before committing, verify that your interpreter is Python 3.12 or newer, because pyproject.toml sets requires-python = ">=3.12", and confirm which backend your environment selects, since the interactive backends pull in Qt, GTK, Tk or wx dependencies that a headless server will not have.

Frequently asked questions

Official sources

1. Issues
2. matplotlib/matplotlib on GitHub
3. Project website
4. README
5. Releases