# pixelmatch > The smallest and fastest pixel-level image comparison library. Latest version **7.2.0** (published 2026-04-29) · ISC license · 0 weekly downloads ## Install ```sh npm install pixelmatch pnpm add pixelmatch yarn add pixelmatch bun add pixelmatch ``` Provides the command `pixelmatch`. ## Health **Score 65/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 7.2.0 | | Published | 2026-04-29 | | First published | 2015-10-14 | | Weekly downloads | 0 | | License | ISC | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 1 | | Unpacked size | 21 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 6958 | | Author | Volodymyr Agafonkin | | Maintainers | mapbox-npm-01, mapbox-npm-02, mapbox-npm-07, mapbox-npm-03, mapbox-npm-04, mapbox-npm-09, mapbox-npm-05, mapbox-npm-06, mapbox-npm-08, mapbox-npm-advanced-actions, mapbox-npm-ci, mapbox-npm, mapbox-admin, mapbox-machine-user, mbx-npm-ci-staging, mbx-npm-ci-production, mbx-npm-01-production, mbx-npm-02-production, mbx-npm-03-production, mbx-npm-04-production, mbx-npm-05-production, mbx-npm-06-production, mbx-npm-07-production, mbx-npm-08-production, mbx-npm-09-production, mbx-npm-02-staging, mbx-npm-advanced-actions-staging, mbx-npm-advanced-actions-production, mourner | | Keywords | image, comparison, diff | ## Links - npm: https://www.npmjs.com/package/pixelmatch - Repository: https://github.com/mapbox/pixelmatch - Homepage: https://github.com/mapbox/pixelmatch#readme - Issues: https://github.com/mapbox/pixelmatch/issues - npm.io page: https://npm.io/package/pixelmatch ## Dependencies (1) - [pngjs](https://npm.io/package/pngjs.md) ^7.0.0 ## Alternatives - [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads - [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads - [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads - [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads - [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads ## Recent versions - 7.2.0 (latest) — 2026-04-29 - 7.1.1 — 2026-04-28 - 7.1.0 — 2025-02-21 - 7.0.0 — 2025-02-21 - 6.0.0 — 2024-06-26 - 5.3.0 — 2022-04-25 - 5.2.1 — 2020-07-01 - 5.2.0 — 2020-04-17 - 5.1.0 — 2019-09-23 - 5.0.2 — 2019-06-10 - 5.0.1 — 2019-06-07 - 5.0.0 — 2019-06-07 - 4.0.2 — 2016-08-08 - 4.0.1 — 2015-12-02 - 4.0.0 — 2015-10-23 - … 7 more at https://npm.io/package/pixelmatch/versions ## README # pixelmatch [![Node](https://github.com/mapbox/pixelmatch/actions/workflows/node.yml/badge.svg)](https://github.com/mapbox/pixelmatch/actions/workflows/node.yml) [![](https://img.shields.io/badge/simply-awesome-brightgreen.svg)](https://github.com/mourner/projects) 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](https://github.com/Huddle/Resemble.js) and [Blink-diff](https://github.com/yahoo/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). ```js const numDiffPixels = pixelmatch(img1, img2, diff, 800, 600, {threshold: 0.1}); ``` Implements ideas from the following papers: - [Measuring perceived color difference using YIQ NTSC transmission color space in mobile applications](https://www.spiedigitallibrary.org/conference-proceedings-of-spie/8011/80119D/Simple-perceptual-color-space-for-color-specification-and-real-time/10.1117/12.901997.full) (2010, Yuriy Kotsarenko, Fernando Ramos) - [Anti-aliased pixel and intensity slope detector](https://www.researchgate.net/publication/234126755_Anti-aliased_Pixel_and_Intensity_Slope_Detector) (2009, Vytautas Vyšniauskas) ## [Demo](https://observablehq.com/@mourner/pixelmatch-demo) ## Example output | expected | actual | diff | | --- | --- | --- | | ![](test/fixtures/4a.png) | ![](test/fixtures/4b.png) | ![1diff](test/fixtures/4diff.png) | | ![](test/fixtures/3a.png) | ![](test/fixtures/3b.png) | ![1diff](test/fixtures/3diff.png) | | ![](test/fixtures/6a.png) | ![](test/fixtures/6b.png) | ![1diff](test/fixtures/6diff.png) | ## API ### 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. - `diffColorAlt` — An alternative color to use for dark on light differences to differentiate between "added" and "removed" parts. If not provided, all differing pixels use the color specified by `diffColor`. `null` 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: ```bash pixelmatch image1.png image2.png output.png 0.1 ``` ## Example usage ### Node.js ```js import fs from 'fs'; import {PNG} from 'pngjs'; import pixelmatch from 'pixelmatch'; const img1 = PNG.sync.read(fs.readFileSync('img1.png')); const img2 = PNG.sync.read(fs.readFileSync('img2.png')); const {width, height} = img1; const diff = new PNG({width, height}); pixelmatch(img1.data, img2.data, diff.data, width, height, {threshold: 0.1}); fs.writeFileSync('diff.png', PNG.sync.write(diff)); ``` ### Browsers ```js const img1 = img1Context.getImageData(0, 0, width, height); const img2 = img2Context.getImageData(0, 0, width, height); const diff = diffContext.createImageData(width, height); pixelmatch(img1.data, img2.data, diff.data, width, height, {threshold: 0.1}); diffContext.putImageData(diff, 0, 0); ``` ## Install Install with NPM: ```bash npm install pixelmatch ``` Or use in the browser from a CDN: ```html