pytest-mpl

library0.19.0pypypi✓ verified 24d ago

pytest-mpl is a pytest plugin designed to facilitate image comparison for Matplotlib figures. It enables users to test their Matplotlib outputs by comparing generated images against reference images using root mean square (RMS) difference or against SHA-256 hashes. The library is actively maintained, with its latest version being 0.19.0, and typically sees a few releases per year.

testing

pip install pytest-mpl

github ↗package ↗

INSTALL

IMPORT

SIG · PYTEST-MPL

pytest-mpl

testingpythonv0.19.0

Install

9.1s avg

Import

—

Disk

196MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.19.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 191.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 9.1s · import 0.000s · 184MB

196MB installed

● package 196MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mpl_image_compare

✓ from pytest_mpl import mpl_image_compare

✗ from pytest_mpl import mpl_image_compare

This example defines a basic pytest function that creates a Matplotlib figure and returns it. The `@pytest.mark.mpl_image_compare` decorator instructs pytest-mpl to compare the generated figure against a baseline. The commands below the code show how to generate initial baseline images and how to run the comparison tests. Ensure a directory named 'baseline_images' (or your chosen path) exists next to your test file.

import matplotlib.pyplot as plt import pytest @pytest.mark.mpl_image_compare def test_simple_plot(): fig, ax = plt.subplots() ax.plot([1, 2, 3], [4, 5, 6]) ax.set_title("A simple line plot") return fig # To generate baseline images (run once or when figures change): # pytest --mpl-generate-path=baseline_images # To run tests and compare against baselines: # pytest --mpl

Debug

Known issues

breakingWhen testing figures within classes, hash library test names generated prior to v0.16.0 will be incompatible. You must regenerate or update baseline image names to include the class name.

fix

Regenerate your hash library or update baseline image filenames to incorporate the class name for affected tests. Refer to the v0.16.0 release notes for details.

affects: >=0.16.0

gotchaTests marked with `@pytest.mark.mpl_image_compare` will only perform image comparison if pytest is run with the `--mpl` command-line option. Without this flag, the tests will execute, but only basic assertions (e.g., that the code runs without error) will be checked, not the visual output.

fix

Always run pytest with `pytest --mpl` to enable image comparison for marked tests. Consider adding `--mpl` to your `pytest.ini` `addopts` for consistent behavior.

affects: All

gotchaBaseline images or hash libraries must be explicitly generated before running image comparison tests. Tests will fail if no reference images/hashes exist or if they are not found in the expected location.

fix

Generate baseline images using `pytest --mpl-generate-path=your_baseline_dir` or a hash library with `pytest --mpl-generate-hash-library=your_hash_library.json`. Store these baselines in a consistent, version-controlled location.

affects: All

gotchaWhen a test marked with `mpl_image_compare` returns a figure, `pytest` versions 7.2 and higher may emit a `PytestReturnNotNoneWarning` if `pytest-mpl` is not properly installed or configured, which could become an exception in future `pytest` releases. Ensure `pytest-mpl` is correctly installed and activated.

fix

Verify `pytest-mpl` is installed (`pip install pytest-mpl`) and that pytest is loading it (check `pytest --trace-config`). `pytest-mpl` has added compatibility for `pytest 7` and `pytest 8.1` in recent versions.

affects: pytest >=7.2

gotchaMatplotlib's rendering can sometimes exhibit minor differences across different operating systems, Python versions, or specific backend configurations (e.g., font rendering). While `pytest-mpl` aims for robustness, ensure your baseline generation environment closely matches your testing environment for cross-platform consistency if this is a concern.

fix

Generate and test baselines in a consistent CI/CD environment or a Docker container to minimize environmental variations. Adjust the `tolerance` parameter in `@pytest.mark.mpl_image_compare` if minor, acceptable differences occur.

affects: All

Upgrade

Version history

0.19.0latest on PyPI · released Mar 25, 2026

Audit

Dependencies

pytestrequiredCore testing framework that pytest-mpl extends.

matplotlibrequiredThe visualization library whose figures are being tested.

PillowoptionalUsed for image manipulation and comparison, often pulled as a transitive dependency of matplotlib or pytest-mpl.

Jinja2optionalUsed for generating HTML summary reports, often pulled as a transitive dependency.

Agent activity

30 hits · last 30 days

node

Resources

githubhttps://github.com/matplotlib/pytest-mpl ↗

packagehttps://pypi.org/project/pytest-mpl/ ↗