---
id: pytest-mpl
version: "0.19.0"
license: BSD-2-Clause
license_treatment: permissive
maintenance: active
---

# pytest-mpl — pytest plugin to help with testing figures output from Matplotlib

License: permissive · Maintenance: active · Downloads: 677.5K/mo

## 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 above — 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

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

- License: BSD-2-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 677.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

matplotlib image comparison testing, pytest visual regression, figure output validation, matplotlib plot testing, image diff testing pytest, visual regression matplotlib, automated figure testing, matplotlib-testing, visual-regression, pytest-plugin

[View on SkillFed](https://skillfed.io/packages/pytest-mpl) · [View on PyPI](https://pypi.org/project/pytest-mpl/)