pytest-mpl

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

pytest-mpl is a pytest plugin that automates visual regression testing for Matplotlib figures by comparing generated images against reference baselines using RMS tolerance or hash comparison.

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

pip install pytest-mpl

uv add pytest-mpl

poetry add pytest-mpl

Installing pytest-mpl

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.

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 --mpl

Requires Python >= 3.10. Matplotlib must be installed and functional in your environment.

Verify 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

Evidence: pytest_mpl-0.19.0-py3-none-any.whl

Tags

More Testing packages