---
id: pixelhog
version: "1.2.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# pixelhog — Rust-accelerated pixelmatch and SSIM for PNG bytes

License: permissive · Maintenance: active · Downloads: 2.1M/mo

## What it is and what it does

Pixelhog is a Rust-backed Python library for comparing pairs of PNG images in two complementary ways: exact pixel-level diff (with anti-alias handling) and structural similarity (SSIM) scoring. It decodes images once at construction and exposes methods on demand through a stateful Comparison object, avoiding redundant I/O. The library also provides spatial clustering to identify where changes occurred, early-exit checks to fail fast on large diffs, and WebP thumbnail generation.

It is designed for visual regression testing in screenshot-based workflows. The package includes batch operations for parallel comparison of many image pairs, support for pre-decoded RGBA buffers (zero-copy), and automatic padding of mismatched image sizes. It has no runtime dependencies beyond the Rust extension itself.

Use it for:

- Automated visual regression testing in UI frameworks to detect unintended rendering changes between baseline and current screenshots.
- Batch processing of many screenshot pairs in parallel to identify which regions of a page changed and by how much.
- Generating diff visualizations and spatial heatmaps to pinpoint layout or styling regressions in web or desktop applications.
- Computing perceptual similarity scores to tolerate minor rendering variations (anti-aliasing, compression) while catching real visual bugs.
- Creating WebP thumbnails of screenshots for archival or reporting without additional image processing dependencies.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Compares PNG screenshots pixel-by-pixel and perceptually using Rust-accelerated algorithms, returning mismatch counts, similarity scores, diff visualizations, and spatial clustering of changes.

Yes, if you need fast visual regression testing on Python 3.12+. The Rust implementation, zero runtime dependencies, and comprehensive API (diff, SSIM, clustering, thumbnails) make it a solid choice for screenshot-based QA. Medium install friction is acceptable for the performance gain. No known vulnerabilities. Verify platform wheel availability for your specific Python version and OS before committing.

## Install

pip install pixelhog
uv add pixelhog
poetry add pixelhog

## Installing pixelhog

Before you install: Medium install friction due to compiled Rust extension; prebuilt wheels available for Python 3.12+ on common platforms (macOS x86/ARM, Linux x86/ARM, Windows x86, musl). Last release 101 days ago; repository active with recent commits.

License in practice: MIT licensed (permissive); no restrictions on commercial or proprietary use.

Quickstart:

from pixelhog import Comparison

cmp = Comparison(baseline_png_bytes, current_png_bytes)
count = cmp.diff_count()
score = cmp.ssim()
diff_png = cmp.diff_image()
result = cmp.clusters(dilation=8, merge_gap=60)

Requires Python 3.12 or later; compiled Rust extension must be available for your platform.

Verify before relying:

- Whether prebuilt wheels cover all target platforms (musl/glibc variants, Python 3.13/3.14 support status).
- Performance characteristics on large images or batch workloads relative to pure-Python alternatives.
- Exact behavior of anti-alias handling and threshold tuning in diff_count().

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 2.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

visual regression testing, screenshot comparison, pixel diff detection, perceptual image similarity, SSIM scoring, image diff clustering, PNG comparison tool, visual-testing, rust-extension, image-processing

[View on SkillFed](https://skillfed.io/packages/pixelhog) · [View on PyPI](https://pypi.org/project/pixelhog/)