pixelhog

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 on this page — 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

pixelhog on PyPI

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

Evidence: pixelhog-1.2.0-cp312-abi3-macosx_10_12_x86_64.whl; pixelhog-1.2.0-cp312-abi3-macosx_11_0_arm64.whl; pixelhog-1.2.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; pixelhog-1.2.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; pixelhog-1.2.0-cp312-abi3-musllinux_1_2_aarch64.whl; pixelhog-1.2.0-cp312-abi3-musllinux_1_2_x86_64.whl; pixelhog-1.2.0-cp312-abi3-win_amd64.whl

Tags

More Quality Assurance packages