pytest-mpl
pytest plugin to help with testing figures output from Matplotlib
Decision gist · record as of 2026-08-14
Yes, if you maintain Matplotlib-heavy code and need automated visual regression testing. The plugin is actively maintained, has no known vulnerabilities, installs with low friction, and integrates seamlessly into pytest workflows. The BSD-2-Clause license is permissive. Install it if visual consistency of plots is part of your test suite; skip it if you don't generate or test figures programmatically.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python >= 3.10.
- Matplotlib must be installed and functional in your environment.
- Low friction installation with a pure-Python wheel.
License · maintenance · safety
BSD-2-Clause (permissive) — BSD-2-Clause is permissive; you can use this in commercial or proprietary projects with minimal restrictions beyond retaining the license notice.
last release 2026-03-25 (142 days) · last repo commit 2026-07-01 · 271 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 677,495 downloads/mo, #5,380 on PyPI
Alternatives
Verify before relying
pip install pytest-mpl
import matplotlib.pyplot as plt
import pytest
@pytest.mark.mpl_image_compare
def test_plot():
fig, ax = plt.subplots()
ax.plot([1, 2])
return fig
# Generate baseline: pytest --mpl-generate-path=baseline
# Run tests: pytest --mpl- Exact tolerance thresholds and RMS calculation method for image comparison
- Performance impact when testing large numbers of figures or high-resolution images
- Compatibility with different Matplotlib backends and rendering engines
What it is and what it does
pytest-mpl bridges the gap between Matplotlib figure generation and automated testing by letting you write test functions that return figures, then comparing their rendered output against stored reference images. It handles the visual regression workflow: generate a baseline set of reference images once, then on subsequent test runs, render new figures and measure the difference (either by RMS of pixel residuals or by hash). If the difference exceeds your tolerance threshold, the test fails, catching unintended changes to plots.
The plugin integrates directly into pytest's test discovery and marking system. You decorate test functions with `@pytest.mark.mpl_image_compare`, and pytest-mpl intercepts them, renders the returned figure to an image, and compares it. It depends on pytest for the test framework, matplotlib for rendering, Pillow for image I/O, Jinja2 for HTML report generation, and packaging for version handling. It's designed for projects that need to ensure plot outputs remain visually consistent across code changes.
Use it for
- Catch unintended changes to scientific plots or data visualizations in CI/CD pipelines
- Verify that refactored plotting code produces identical visual output before and after
- Maintain visual regression baselines for library documentation or gallery examples
- Test custom Matplotlib extensions or themes to ensure consistent rendering across versions
- Validate plot appearance across different environments or backend configurations
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes, if you maintain Matplotlib-heavy code and need automated visual regression testing.
The plugin is actively maintained, has no known vulnerabilities, installs with low friction, and integrates seamlessly into pytest workflows. The BSD-2-Clause license is permissive. Install it if visual consistency of plots is part of your test suite; skip it if you don't generate or test figures programmatically.
Install
pytest-mpl on PyPI
Before you install
Low friction installation with a pure-Python wheel. Active maintenance (last commit 2026-07-01) and stable status since early releases (2015). Depends on pytest, matplotlib, and common utilities—all widely used and well-maintained.
Requires Python >= 3.10. Matplotlib must be installed and functional in your environment.
License in practice
BSD-2-Clause is permissive; you can use this in commercial or proprietary projects with minimal restrictions beyond retaining the license notice.
Quickstart
pip install pytest-mpl
import matplotlib.pyplot as plt
import pytest
@pytest.mark.mpl_image_compare
def test_plot():
fig, ax = plt.subplots()
ax.plot([1, 2])
return fig
# Generate baseline: pytest --mpl-generate-path=baseline
# Run tests: pytest --mplVerify before relying
- Exact tolerance thresholds and RMS calculation method for image comparison
- Performance impact when testing large numbers of figures or high-resolution images
- Compatibility with different Matplotlib backends and rendering engines
Package facts
| License | BSD-2-Clause permissive |
| Python support | Supports the current Python release >=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 5 packagespytestmatplotlibpackagingJinja2Pillow |
| Maintenance | Actively maintained 142 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 677,495 / month, #5,380 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableFramework :: PytestIntended Audience :: DevelopersOperating System :: OS IndependentProgramming Language :: PythonProgramming Language :: Python :: 3Topic :: Scientific/Engineering :: VisualizationTopic :: Software Development :: Testing |
Evidence: pytest_mpl-0.19.0-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “matplotlib image comparison testing”
- pytest-mplpytest-mpl is a pytest plugin that automates visual regression…
- pixelhogCompares PNG screenshots pixel-by-pixel and perceptually using…
- pixelmatchCompares two images pixel-by-pixel to detect differences, with…
Give your agent the search over MCP, or paste the wish link into any chat.
More Testing packages
Pluggy provides a plugin system that lets you define hook specifications and register implementations to be called in sequence, enabling extensible Python applications without tight coupling.
Install it if you're building an extensible application or framework.
pytest is a testing framework that lets you write test functions using plain assert statements and automatically discovers and runs them, with detailed failure reporting.
virtualenv creates isolated Python environments where packages can be installed independently without affecting the system Python or other projects.
Coverage.py measures which lines of Python code are executed during test runs, reporting coverage percentages and identifying untested code paths.
Install it if you want to measure test completeness or enforce coverage thresholds in your project.
pytest-asyncio is a pytest plugin that enables writing and running async test functions using the asyncio library, allowing developers to await code directly within test cases.
Install it if you write tests for any asyncio-based code.
A pytest plugin that generates test reports in Common Test Report Format (CTRF) as JSON, compatible with pytest-xdist and pytest-playwright for distributed and browser-based testing.
Install it if you need CTRF-formatted test output for CI/CD integration or cross-tool reporting.
See also pytest-regressions · pytest-playwright-visual · matplotlib · matplotlib-inline · pixelhog · pytest-textual-snapshot · lovelyplots · pytest-arraydiff · plotly-resampler · imgcat