pixelmatch — Fast Pixel-Level Image Comparison Library

Introduction

pixelmatch is a tiny, dependency-free JavaScript library by Mapbox that compares two images pixel by pixel and outputs a diff image highlighting the differences. It uses a perceptual color distance metric (YIQ) that aligns with how humans perceive color differences, making it effective for visual regression testing where minor antialiasing or rendering variations should not trigger false positives.

What pixelmatch Does

• Compares two images pixel by pixel and returns the count of differing pixels along with an optional diff image
• Uses a YIQ-based perceptual color distance algorithm that models human vision sensitivity to luminance and chrominance
• Detects antialiased pixels and can optionally ignore them to reduce false positives in cross-platform rendering
• Runs in both Node.js and browser environments with no external dependencies
• Processes raw RGBA pixel data arrays, making it compatible with any image loading library

Architecture Overview

pixelmatch operates on flat Uint8Array buffers of RGBA pixel data. For each pixel, it computes the color distance using a weighted YIQ formula that emphasizes luminance differences over chrominance, matching human perceptual sensitivity. Antialiasing detection works by checking whether a pixel sits on a boundary between two distinct regions (a contrast edge) and whether neighboring pixels show a smooth gradient. The entire algorithm runs in a single pass over the pixel data with O(width x height) complexity and minimal memory allocation.

Self-Hosting & Configuration

• Install via npm: npm install pixelmatch
• No build step required; works as an ES module or CommonJS import
• Configure the comparison threshold (0 to 1) to control sensitivity to color differences
• Toggle antialiasing detection with the includeAA option
• Customize the diff output color and alpha to match your reporting preferences

Key Features

• Under 150 lines of code with zero dependencies, keeping bundle size minimal
• Perceptual color distance metric that reduces false positives from rendering engine differences
• Antialiasing-aware comparison that handles font rendering and shape edge variations across platforms
• Configurable threshold for tuning sensitivity between strict pixel-exact and loose perceptual matching
• Returns both a numeric diff count and an optional visual diff image for human review

Comparison with Similar Tools

• Resemble.js — Feature-rich image comparison with tolerance settings; pixelmatch is smaller and faster for CI pipelines
• looks-same — Yandex image comparison tool with antialiasing support; pixelmatch has a simpler API and lighter footprint
• jest-image-snapshot — Jest plugin for visual regression; uses pixelmatch internally for the comparison step
• BackstopJS — Visual regression testing framework; pixelmatch serves as the diff engine rather than a full test runner
• Applitools — Cloud-based visual testing with AI; pixelmatch is open source and runs locally without external services

FAQ

Q: What image formats does pixelmatch accept? A: pixelmatch works with raw RGBA pixel data (Uint8Array or Uint8ClampedArray). Use libraries like pngjs, sharp, or Canvas API to decode images into pixel buffers before passing them.

Q: How do I choose the right threshold value? A: The default threshold of 0.1 works well for most visual regression scenarios. Lower values (0.01-0.05) catch subtle color shifts; higher values (0.2-0.5) tolerate rendering engine differences.

Q: Can pixelmatch run in the browser? A: Yes. It works with Canvas ImageData objects directly. Extract pixel data from canvas elements and pass the data arrays to pixelmatch.

Q: How fast is pixelmatch? A: pixelmatch compares a 1920x1080 image pair in roughly 20-50ms on modern hardware, making it suitable for CI pipelines with hundreds of screenshots.

Sources

• https://github.com/mapbox/pixelmatch
• https://www.npmjs.com/package/pixelmatch