{"id":5429,"library":"pytest-mpl","title":"pytest-mpl","description":"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.","status":"active","version":"0.19.0","language":"en","source_language":"en","source_url":"https://github.com/matplotlib/pytest-mpl","tags":["pytest","testing","matplotlib","image comparison","figures","visualization"],"install":[{"cmd":"pip install pytest-mpl","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core testing framework that pytest-mpl extends.","package":"pytest"},{"reason":"The visualization library whose figures are being tested.","package":"matplotlib"},{"reason":"Used for image manipulation and comparison, often pulled as a transitive dependency of matplotlib or pytest-mpl.","package":"Pillow","optional":true},{"reason":"Used for generating HTML summary reports, often pulled as a transitive dependency.","package":"Jinja2","optional":true}],"imports":[{"note":"The core decorator to mark a test function for Matplotlib image comparison.","symbol":"mpl_image_compare","correct":"import pytest\n\n@pytest.mark.mpl_image_compare"}],"quickstart":{"code":"import matplotlib.pyplot as plt\nimport pytest\n\n@pytest.mark.mpl_image_compare\ndef test_simple_plot():\n    fig, ax = plt.subplots()\n    ax.plot([1, 2, 3], [4, 5, 6])\n    ax.set_title(\"A simple line plot\")\n    return fig\n\n# To generate baseline images (run once or when figures change):\n# pytest --mpl-generate-path=baseline_images\n\n# To run tests and compare against baselines:\n# pytest --mpl","lang":"python","description":"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."},"warnings":[{"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.","message":"When 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.","severity":"breaking","affected_versions":">=0.16.0"},{"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.","message":"Tests 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Baseline 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"pytest >=7.2"},{"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.","message":"Matplotlib'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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}