{"id":4170,"library":"pixelmatch","title":"pixelmatch","description":"pixelmatch-py is a fast, pure-Python library for pixel-level image comparison, originally designed for comparing screenshots in tests. It provides accurate anti-aliased pixel detection and perceptual color difference metrics. This library is a Python port of the popular JavaScript `mapbox/pixelmatch` library and currently supports Python versions 3.10 and newer, with a stable release cadence.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/whtsky/pixelmatch-py","tags":["image comparison","image diff","screenshot testing","PIL","Pillow","computer vision"],"install":[{"cmd":"pip install pixelmatch","lang":"bash","label":"Install stable version"},{"cmd":"pip install pixelmatch pillow","lang":"bash","label":"Install with Pillow for PIL.Image support"}],"dependencies":[{"reason":"Required for comparing PIL.Image instances, a common use case.","package":"Pillow","optional":true}],"imports":[{"note":"For comparing raw RGBA image data (byte arrays).","symbol":"pixelmatch","correct":"from pixelmatch import pixelmatch"},{"note":"For comparing PIL.Image instances.","symbol":"pixelmatch","correct":"from pixelmatch.contrib.PIL import pixelmatch"}],"quickstart":{"code":"from PIL import Image\nfrom pixelmatch.contrib.PIL import pixelmatch\nimport io\n\ndef create_dummy_image(width, height, color):\n    img = Image.new('RGBA', (width, height), color)\n    return img\n\n# Create two identical images\nimg1 = create_dummy_image(100, 100, (255, 0, 0, 255)) # Red image\nimg2 = create_dummy_image(100, 100, (255, 0, 0, 255)) # Red image\n\n# Make a slight difference in img2\nimg2.putpixel((10, 10), (0, 0, 255, 255)) # Blue pixel at (10,10)\n\nimg_diff = Image.new('RGBA', img1.size)\n\nmismatch = pixelmatch(img1, img2, img_diff, threshold=0.1, includeAA=True)\n\nprint(f\"Number of mismatched pixels: {mismatch}\")\n\n# Save the diff image (optional, for visualization)\n# To run this, you'd need actual file paths or use BytesIO\n# with open('diff.png', 'wb') as f:\n#    img_diff.save(f, format='PNG')\n# print(\"Diff image saved as diff.png\")\n","lang":"python","description":"This example demonstrates how to compare two PIL.Image instances, highlight their differences, and get the count of mismatched pixels. It creates two dummy images, introduces a single pixel difference, and then uses `pixelmatch` to compare them. The `img_diff` object will contain the visual representation of the differences."},"warnings":[{"fix":"Review your test expectations if you rely on precise grayscale values in the diff output when `diff_mask=False` and images are nearly identical. No action needed if you primarily use the mismatch count or `diff_mask=True`.","message":"`pixelmatch.contrib.PIL.pixelmatch` now uses a fast path for byte-identical images. When an `output` image is provided and `diff_mask=False`, grayscale diff output values can differ slightly (typically up to +/-1 per channel due to PIL rounding) compared to previous versions. This primarily affects the exact pixel values of the generated diff image, not the mismatch count.","severity":"breaking","affected_versions":">=0.3.1"},{"fix":"Ensure your project runs on Python 3.10 or newer.","message":"Support for older Python versions (3.7-3.9) has been dropped.","severity":"breaking","affected_versions":">=0.3.1"},{"fix":"Always ensure `img1` and `img2` have the same width and height before passing them to `pixelmatch`.","message":"The primary `pixelmatch` function (for raw image data) and the PIL-contributed `pixelmatch` function expect input images to have identical dimensions. If dimensions differ, an error will be raised or unexpected results may occur.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure raw image data is in the expected RGBA byte array format.","message":"For raw image data comparison, the `pixelmatch` function expects RGBA image data (e.g., a byte array where pixels are represented as [R, G, B, A, R, G, B, A, ...]). Incorrect data format will lead to wrong comparisons or errors.","severity":"gotcha","affected_versions":"All"},{"fix":"For highly performant image comparison, consider using `pybind11-pixelmatch` instead, which is a separate package with a C++ backend. Be aware that its API might differ slightly.","message":"The `pixelmatch` (pure Python) package is significantly slower than its C++-bound alternative, `pybind11-pixelmatch`, especially for large images or frequent comparisons. While `pixelmatch` is a pure Python port, `pybind11-pixelmatch` offers superior performance for performance-critical applications.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}