PHPackages spatie/pixelmatch-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Image & Media](/categories/media) 4. / 5. spatie/pixelmatch-php ActiveLibrary[Image & Media](/categories/media) spatie/pixelmatch-php ===================== Compare images using PHP 1.2.1(7mo ago)58104.2k—4.1%68MITPHPPHP ^8.1CI passing Since Sep 11Pushed 1w ago2 watchersCompare [ Source](https://github.com/spatie/pixelmatch-php)[ Packagist](https://packagist.org/packages/spatie/pixelmatch-php)[ Docs](https://github.com/spatie/pixelmatch-php)[ GitHub Sponsors](https://github.com/spatie)[ RSS](/packages/spatie-pixelmatch-php/feed)WikiDiscussions main Synced 2d ago READMEChangelog (6)Dependencies (5)Versions (8)Used By (8) Compare images using PHP ======================== [](#compare-images-using-php) [![Latest Version on Packagist](https://camo.githubusercontent.com/a0ef2711b89ef4e72ba39acd3a9b31b8d39840116b19e7fd70af3274e239a07a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f706978656c6d617463682d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/pixelmatch-php)[![Tests](https://github.com/spatie/pixelmatch-php/actions/workflows/run-tests.yml/badge.svg)](https://github.com/spatie/pixelmatch-php/actions/workflows/run-tests.yml)[![Total Downloads](https://camo.githubusercontent.com/b3122348785ff22de07efbbbb4c530e83c3c104f6b6d2dbef0354d40c699eb2e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f706978656c6d617463682d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/pixelmatch-php) This package can compare two images and return the percentage of matching pixels. It's a PHP wrapper around the [Pixelmatch](https://github.com/mapbox/pixelmatch) JavaScript library. Here's a quick example on how to use the package. ``` use Spatie\Pixelmatch\Pixelmatch; $pixelmatch = Pixelmatch::new("path/to/file1.png", "path/to/file2.png"); $pixelmatch->matchedPixelPercentage(); // returns a float, for example 97.5 $pixelmatch->mismatchedPixelPercentage(); // returns a float, for example 2.5 ``` Support us ---------- [](#support-us) [![](https://camo.githubusercontent.com/d6ce4e782aeaeb8049f9fcc4fbaade4de2ffc3f005666a326024f0e47ce8d9f0/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f706978656c6d617463682d7068702e6a70673f743d31)](https://spatie.be/github-ad-click/pixelmatch-php) We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us). We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards). Installation ------------ [](#installation) You can install the package via composer: ``` composer require spatie/pixelmatch-php ``` In your project, or on your server, you must have the JavaScript package [`Pixelmatch`](https://github.com/mapbox/Pixelmatch) installed. ``` npm install pixelmatch ``` ... or Yarn. ``` yarn add pixelmatch ``` Make sure you have installed Node 16 or higher. Usage ----- [](#usage) Here's how you can get the percentage of matching pixels between two images. ``` use Spatie\Pixelmatch\Pixelmatch; $pixelmatch = Pixelmatch::new("path/to/file1.png", "path/to/file2.png"); $pixelmatch->matchedPixelPercentage(); // returns a float, for example 97.5 $pixelmatch->mismatchedPixelPercentage(); // returns a float, for example 2.5 ``` To get the amount of matched and mismatched pixels, you can use these methods. ``` use Spatie\Pixelmatch\Pixelmatch; $pixelmatch = Pixelmatch::new("path/to/file1.png", "path/to/file2.png"); $pixelmatch->matchedPixels(); // returns an int $pixelmatch->mismatchedPixels(); // returns an int ``` You can use the `matches function` to check if the images match. ``` use Spatie\Pixelmatch\Pixelmatch; $pixelmatch = Pixelmatch::new("path/to/file1.png", "path/to/file2.png"); $pixelmatch->matches(); // returns a boolean $pixelmatch->doesNotMatch(); // returns a boolean ``` ### Setting a threshold [](#setting-a-threshold) To set the threshold for the amount of mismatching pixels, you can use the `threshold` method. Higher values will make the comparison more sensitive. The threshold should be between 0 and 1. If you don't set a threshold, we'll use the default value of `0.1`. ``` $pixelmatch->threshold(0.05); ``` ### Ignoring anti-aliasing [](#ignoring-anti-aliasing) To ignore anti-aliased pixels, you can use the `includeAa` method. ``` $pixelmatch->includeAa(); ``` Limitations ----------- [](#limitations) The package can only compare png images. Images with different dimensions cannot be compared. If you try to do this, a `Spatie\Pixelmatch\Exceptions\CouldNotCompare` exception will be thrown. Testing ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [Niels Vanpachtenbeke](https://github.com/nielsvanpach) - [Freek Van der Herten](https://github.com/freekmurze) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 56 — FairBetter than 97% of packages Maintenance83 Actively maintained with recent releases Popularity46 Moderate usage in the ecosystem Community29 Small or concentrated contributor base Maturity57 Maturing project, gaining track record Bus Factor1 Top contributor holds 54.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~161 days Recently: every ~201 days Total 6 Last Release 221d ago Major Versions 0.0.2 → 1.0.02023-09-11 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie) --- Top Contributors [![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (85 commits)")[![Nielsvanpach](https://avatars.githubusercontent.com/u/10651054?v=4)](https://github.com/Nielsvanpach "Nielsvanpach (28 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (23 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (10 commits)")[![Chris8934](https://avatars.githubusercontent.com/u/44963939?v=4)](https://github.com/Chris8934 "Chris8934 (3 commits)")[![thecaliskan](https://avatars.githubusercontent.com/u/13554944?v=4)](https://github.com/thecaliskan "thecaliskan (2 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (2 commits)")[![riasvdv](https://avatars.githubusercontent.com/u/3626559?v=4)](https://github.com/riasvdv "riasvdv (1 commits)")[![onlime](https://avatars.githubusercontent.com/u/2759561?v=4)](https://github.com/onlime "onlime (1 commits)") --- Tags imagesphppixelmatchspatieimagespixelmatch-phpPixelmatch ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/spatie-pixelmatch-php/health.svg) ``` [![Health](https://phpackages.com/badges/spatie-pixelmatch-php/health.svg)](https://phpackages.com/packages/spatie-pixelmatch-php) ``` ### Alternatives [spatie/image Manipulate images with an expressive API 1.4k60.7M189](/packages/spatie-image)[spatie/image-optimizer Easily optimize images using PHP 2.9k79.5M160](/packages/spatie-image-optimizer)[matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.7k38.9k](/packages/matomo-matomo)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)