{"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":"python","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,"search_vec":"'3.10':55 'accur':27 'alias':30 'anti':29 'anti-alias':28 'cadenc':62 'color':35 'compar':21 'comparison':17,64 'comput':71 'current':51 'design':19 'detect':32 'diff':66 'differ':36 'fast':7 'imag':16,63,65 'javascript':47 'level':15 'librari':11,39,49 'mapbox/pixelmatch':48 'metric':37 'newer':57 'origin':18 'perceptu':34 'pil':69 'pillow':70 'pixel':14,31 'pixel-level':13 'pixelmatch':1,3 'pixelmatch-pi':2 'popular':46 'port':43 'provid':26 'pure':9 'pure-python':8 'py':4 'python':10,42,53 'releas':61 'screenshot':22,67 'stabl':60 'support':52 'test':24,68 'version':54 'vision':72","created_at":"2026-04-12T03:43:57.129569+00:00","updated_at":"2026-04-17T14:25:21.110539+00:00","problems":[{"fix":"Ensure the library is installed using pip: `pip install pixelmatch` (or `pip install pixelmatch pillow` if using PIL integration).","cause":"The 'pixelmatch' library is not installed in the current Python environment or the import statement is incorrect.","error":"ModuleNotFoundError: No module named 'pixelmatch'"},{"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.","cause":"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.","error":"ValueError: Input images must have identical dimensions"},{"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.","cause":"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.","error":"ValueError: Raw image data must be in RGBA byte array format"},{"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`.","cause":"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).","error":"ValueError: Images must be numpy arrays of shape (height, width, 3) or (height, width, 4) and dtype uint8."},{"fix":"Import and call the correct function: `from pixelmatch import pixelmatch` then `pixelmatch(img1, img2, ...)`.","cause":"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`.","error":"AttributeError: module 'pixelmatch' has no attribute 'compare_images'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/whtsky/pixelmatch-py","docs":null,"changelog":null,"pypi":"https://pypi.org/project/pixelmatch/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}