Odiff Image Diffing

odiff Image Diffing

odiff is a native, SIMD-accelerated, pixel-by-pixel image comparator. It is the fastest popular image-diff tool in its class (~10-100x faster than pixelmatch / resemble.js), supports PNG/JPEG/WebP/TIFF/BMP, writes a diff artifact to disk, and exits with structured codes that make it CI-friendly.

When to Use This Skill

Installation

# Recommended: npm package ships the native binary
npm install -g odiff-bin

# Project-local
npm install --save-dev odiff-bin

# Verify
odiff --version

The npm package is odiff-bin; the installed command is odiff. Native binaries are also available from GitHub Releases for sandboxes without npm registry access.

Core Usage

odiff <base_image> <comp_image> [diff_output] [options]

• base_image and comp_image are the two images to compare. Any of PNG, JPEG, WebP, TIFF, BMP. Cross-format compares are fine.
• diff_output is an optional PNG path. When supplied, odiff writes a visual diff highlighting the changed pixels in #cd2cc9 magenta.
• Exit code carries the verdict — read it instead of parsing prose stdout.

odiff before.png after.png diff.png

Exit Codes

odiff is exit-code-first by design. Branch on the exit code, not on stdout text:

CI pattern:

if odiff before.png after.png diff.png --parsable-stdout; then
  echo "visual match"
else
  code=$?
  echo "visual drift (exit $code) — see diff.png"
  exit $code
fi

Machine-Readable Output

--parsable-stdout swaps the human report for a single line that's trivial to parse:

Pair with the exit code for a complete verdict; the line itself is the metric to log or post as a CI annotation.

Composition Recipes

1. Before/After diff with playwright-cli

playwright-cli saves PNG screenshots to .playwright-cli/. Pair the two ends of a change with odiff to confirm the visual delta is what you expected.

# Baseline
playwright-cli goto https://app.example.com/dashboard
playwright-cli screenshot --filename=baseline.png

# Make the code change, then re-screenshot
playwright-cli goto https://app.example.com/dashboard
playwright-cli screenshot --filename=current.png

# Diff — exit 0 = visually unchanged, exit 22 = drift
odiff .playwright-cli/baseline.png .playwright-cli/current.png \
  .playwright-cli/diff.png --parsable-stdout --antialiasing

--antialiasing ignores antialiased pixels, which suppresses noise from font-rendering jitter across runs.

2. Batch directory compare

For a baseline directory (golden files) and a current directory (fresh renders), iterate matched filenames:

baseline_dir=tests/__snapshots__
current_dir=tests/__current__
mkdir -p tests/__diff__

fail=0
for img in "$baseline_dir"/*.png; do
  name=$(basename "$img")
  current="$current_dir/$name"
  diff="tests/__diff__/$name"

  if odiff "$img" "$current" "$diff" --parsable-stdout --antialiasing; then
    echo "OK    $name"
  else
    echo "DRIFT $name"
    fail=1
  fi
done

exit $fail

3. CI exit-code pattern with layout protection

Treat layout changes as a distinct failure mode from pixel drift — a layout shift usually wants human attention, while a pixel diff may be tolerable under a small threshold.

odiff before.png after.png diff.png \
  --fail-on-layout \
  --threshold 0.05 \
  --antialiasing \
  --parsable-stdout
case $? in
  0)  echo "::notice::visual unchanged" ;;
  21) echo "::error::layout shifted — review diff.png"; exit 1 ;;
  22) echo "::warning::pixel drift — review diff.png"; exit 1 ;;
  *)  echo "::error::odiff failure"; exit 1 ;;
esac

Advanced Options

Agentic Optimizations

Quick Reference

See Also

• playwright-cli — produces the .playwright-cli/*.png screenshots that odiff consumes
• playwright-testing — Playwright's own toHaveScreenshot() snapshot assertions for in-test diffing
• imagemagick-conversion — pre-process images (resize, normalize format) before diffing
• configure-ux-testing — set up a full visual-regression pipeline with snapshot directories
• Official site: https://odiff.opa.dev
• Repository: https://github.com/dmtrKovalenko/odiff
• npm: https://www.npmjs.com/package/odiff-bin