Skip to content
The smallest, simplest and fastest JavaScript pixel-level image comparison library
Branch: master
Clone or download
Latest commit 0eb801b Sep 23, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin minor clean up of CLI code Jun 6, 2019
test Add `diffMask` option (#73) Sep 23, 2019
.gitignore more test fixtures Oct 18, 2015
.travis.yml update travis node version Jan 30, 2019
LICENSE upgrade to ES6 syntax; simplify with sync read/write Jun 6, 2019 update CDN url Sep 23, 2019
index.js Add `diffMask` option (#73) Sep 23, 2019
package.json 5.1.0 Sep 23, 2019
yarn.lock upgrade deps and commit yarn.lock Sep 23, 2019


Build Status

The smallest, simplest and fastest JavaScript pixel-level image comparison library, originally created to compare screenshots in tests.

Features accurate anti-aliased pixels detection and perceptual color difference metrics.

Inspired by Resemble.js and Blink-diff. Unlike these libraries, pixelmatch is around 150 lines of code, has no dependencies, and works on raw typed arrays of image data, so it's blazing fast and can be used in any environment (Node or browsers).

const numDiffPixels = pixelmatch(img1, img2, diff, 800, 600, {threshold: 0.1});

Implements ideas from the following papers:


Example output

expected actual diff


pixelmatch(img1, img2, output, width, height[, options])

  • img1, img2 — Image data of the images to compare (Buffer, Uint8Array or Uint8ClampedArray). Note: image dimensions must be equal.
  • output — Image data to write the diff to, or null if don't need a diff image.
  • width, height — Width and height of the images. Note that all three images need to have the same dimensions.

options is an object literal with the following properties:

  • threshold — Matching threshold, ranges from 0 to 1. Smaller values make the comparison more sensitive. 0.1 by default.
  • includeAA — If true, disables detecting and ignoring anti-aliased pixels. false by default.
  • alpha — Blending factor of unchanged pixels in the diff output. Ranges from 0 for pure white to 1 for original brightness. 0.1 by default.
  • aaColor — The color of anti-aliased pixels in the diff output in [R, G, B] format. [255, 255, 0] by default.
  • diffColor — The color of differing pixels in the diff output in [R, G, B] format. [255, 0, 0] by default.
  • diffMask — Draw the diff over a transparent background (a mask), rather than over the original image. Will not draw anti-aliased pixels (if detected).

Compares two images, writes the output diff and returns the number of mismatched pixels.

Command line

Pixelmatch comes with a binary that works with PNG images:

pixelmatch image1.png image2.png output.png 0.1

Example usage


const fs = require('fs');
const PNG = require('pngjs').PNG;
const pixelmatch = require('pixelmatch');

const img1 ='img1.png'));
const img2 ='img2.png'));
const {width, height} = img1;
const diff = new PNG({width, height});

pixelmatch(,,, width, height, {threshold: 0.1});

fs.writeFileSync('diff.png', PNG.sync.write(diff));


const img1 = img1Context.getImageData(0, 0, width, height);
const img2 = img2Context.getImageData(0, 0, width, height);
const diff = diffContext.createImageData(width, height);

pixelmatch(,,, width, height, {threshold: 0.1});

diffContext.putImageData(diff, 0, 0);


Install with NPM:

npm install pixelmatch

Use in the browser from a CDN:

<script src=""></script>


You can’t perform that action at this time.