pixelmatch

library0.4.0pypypi✓ verified 22d ago

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.

testing

pip install pixelmatch

github ↗package ↗

INSTALL

IMPORT

SIG · PIXELMATCH

pixelmatch

testingpythonv0.4.0

Install

1.9s avg

Import

12ms

Disk

36MB

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.4.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.910 runs

installs and imports cleanly · install 0.0s · import 0.012s · 37.5MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.9s · import 0.010s · 38MB

36MB installed

● package 36MB

Code

Verified usage

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

pixelmatch

✓ from pixelmatch import pixelmatch

For comparing raw RGBA image data (byte arrays).

pixelmatch

✓ from pixelmatch.contrib.PIL import pixelmatch

For comparing PIL.Image instances.

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.

from PIL import Image from pixelmatch.contrib.PIL import pixelmatch import io def create_dummy_image(width, height, color): img = Image.new('RGBA', (width, height), color) return img # Create two identical images img1 = create_dummy_image(100, 100, (255, 0, 0, 255)) # Red image img2 = create_dummy_image(100, 100, (255, 0, 0, 255)) # Red image # Make a slight difference in img2 img2.putpixel((10, 10), (0, 0, 255, 255)) # Blue pixel at (10,10) img_diff = Image.new('RGBA', img1.size) mismatch = pixelmatch(img1, img2, img_diff, threshold=0.1, includeAA=True) print(f"Number of mismatched pixels: {mismatch}") # Save the diff image (optional, for visualization) # To run this, you'd need actual file paths or use BytesIO # with open('diff.png', 'wb') as f: # img_diff.save(f, format='PNG') # print("Diff image saved as diff.png")

Debug

Known issues

breaking`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.

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`.

affects: >=0.3.1

breakingSupport for older Python versions (3.7-3.9) has been dropped.

fix

Ensure your project runs on Python 3.10 or newer.

affects: >=0.3.1

gotchaThe 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.

fix

Always ensure `img1` and `img2` have the same width and height before passing them to `pixelmatch`.

affects: All

gotchaFor 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.

fix

Ensure raw image data is in the expected RGBA byte array format.

affects: All

gotchaThe `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.

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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pixelmatch'

The 'pixelmatch' library is not installed in the current Python environment or the import statement is incorrect.

fix

Ensure the library is installed using pip: `pip install pixelmatch` (or `pip install pixelmatch pillow` if using PIL integration).

ValueError: Input images must have identical dimensions

The `pixelmatch` function (both for raw data and PIL images) requires that the two input images (`img1` and `img2`) have the exact same width and height.

fix

Before passing images to `pixelmatch`, ensure `img1` and `img2` have been resized or cropped to matching dimensions. For PIL images, you can use `img.resize()` or `img.crop()` to standardize their sizes.

ValueError: Raw image data must be in RGBA byte array format

When using the primary `pixelmatch` function for raw image data, the input images (`img1`, `img2`, and `output`) are expected to be byte arrays where each pixel is represented by four channels: Red, Green, Blue, and Alpha.

fix

Convert your raw image data into the RGBA byte array format before passing it to the `pixelmatch` function. If you are working with PIL images, use `pixelmatch.contrib.PIL.pixelmatch` instead, which directly accepts `PIL.Image` objects.

ValueError: Images must be numpy arrays of shape (height, width, 3) or (height, width, 4) and dtype uint8.

The input images are not provided as NumPy arrays with the required shape (height, width, channels) and `uint8` data type (e.g., they are PIL Image objects, or NumPy arrays with incorrect dimensions or dtype).

fix

Convert the images to a `numpy.ndarray` with `dtype=np.uint8` and shape `(height, width, 3)` (RGB) or `(height, width, 4)` (RGBA) before passing them to `pixelmatch`.

AttributeError: module 'pixelmatch' has no attribute 'compare_images'

The user is attempting to call a function (e.g., `compare_images`) that does not exist within the `pixelmatch` module. The primary image comparison function is also named `pixelmatch`.

fix

Import and call the correct function: `from pixelmatch import pixelmatch` then `pixelmatch(img1, img2, ...)`.

Upgrade

Version history

0.4.0latest on PyPI · released Mar 7, 2026

Audit

Dependencies

PillowoptionalRequired for comparing PIL.Image instances, a common use case.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/whtsky/pixelmatch-py ↗

packagehttps://pypi.org/project/pixelmatch/ ↗