compare — Compare Images and Generate a Difference Image

ImageMagick's compare puts two images side by side and surfaces every difference – both as a colour-highlighted diff image and as a measurable number. Use it to check whether a rendering, an export or a screenshot has drifted from a reference. Metrics such as AE, RMSE or SSIM together with the exit code make the comparison scriptable – ideal for visual regression tests in CI/CD pipelines. On ImageMagick 7, prefer calling it as magick compare.

Basic Comparison

compare <image1> <image2> <diff-output> — Create a visual diff image highlighting differences in red.

compare original.png modified.png diff.png

compare -metric AE <image1> <image2> null: — Count the number of different pixels (Absolute Error).

compare -metric AE original.png modified.png null:

compare -metric RMSE <image1> <image2> null: — Calculate Root Mean Square Error between images.

compare -metric RMSE original.png modified.png null:

compare -metric SSIM <image1> <image2> null: — Calculate Structural Similarity Index (1.0 = identical).

compare -metric SSIM original.png modified.png null:

Comparison Metrics

compare -metric AE <image1> <image2> null: — Absolute Error: total count of different pixels.

compare -metric AE baseline.png current.png null:

compare -metric MAE <image1> <image2> null: — Mean Absolute Error: average difference per pixel.

compare -metric MAE baseline.png current.png null:

compare -metric MSE <image1> <image2> null: — Mean Squared Error: average of squared differences.

compare -metric MSE baseline.png current.png null:

compare -metric PSNR <image1> <image2> null: — Peak Signal-to-Noise Ratio (higher = more similar, inf = identical).

compare -metric PSNR baseline.png current.png null:

compare -metric PHASH <image1> <image2> null: — Perceptual Hash: perceptual difference (0 = identical).

compare -metric PHASH baseline.png current.png null:

compare -metric NCC <image1> <image2> null: — Normalized Cross-Correlation (1.0 = identical).

compare -metric NCC baseline.png current.png null:

Visual Diff Styles

compare -highlight-color <color> <image1> <image2> <diff> — Set the color used to highlight differences.

compare -highlight-color blue original.png modified.png diff.png

compare -lowlight-color <color> <image1> <image2> <diff> — Set the color for unchanged areas.

compare -lowlight-color white original.png modified.png diff.png

compare -compose src <image1> <image2> <diff> — Show only the different pixels (transparent elsewhere).

compare -compose src original.png modified.png diff.png

compare -fuzz <percent>% <image1> <image2> <diff> — Allow tolerance for near-matching pixels.

compare -fuzz 5% original.png modified.png diff.png

compare -fuzz <percent>% -metric AE <image1> <image2> null: — Count differences with color tolerance.

compare -fuzz 2% -metric AE original.png modified.png null:

Subimage Search

compare -subimage-search <small> <large> <diff> — Find a smaller image within a larger image.

compare -subimage-search icon.png screenshot.png match.png

compare -subimage-search -metric RMSE <small> <large> null: — Find subimage and report similarity score.

compare -subimage-search -metric RMSE button.png screenshot.png null:

compare -subimage-search -dissimilarity-threshold <n> <small> <large> <diff> — Set threshold for subimage search (0.0 = exact, 1.0 = any match).

compare -subimage-search -dissimilarity-threshold 0.2 icon.png page.png match.png

CI/CD & Automation

compare -metric AE -fuzz 1% <baseline> <current> diff.png && echo 'PASS' || echo 'FAIL' — Compare with exit code (0 = identical, 1 = different).

compare -metric AE -fuzz 1% baseline.png screenshot.png diff.png && echo 'PASS' || echo 'FAIL'

DIFF=$(compare -metric AE <baseline> <current> null: 2>&1); [ "$DIFF" -lt <threshold> ] — Check if pixel difference is below a threshold.

DIFF=$(compare -metric AE baseline.png current.png null: 2>&1); [ "$DIFF" -lt 100 ] && echo 'OK' || echo 'Too many changes'

compare -metric SSIM <image1> <image2> null: 2>&1 — Capture SSIM score (outputs to stderr, redirect to capture).

SSIM=$(compare -metric SSIM baseline.png current.png null: 2>&1); echo "Similarity: $SSIM"

for f in baseline/*.png; do compare -metric AE "$f" "current/$(basename $f)" "diff/$(basename $f)" 2>&1; done — Batch compare all baseline images against current versions.

for f in baseline/*.png; do echo "$(basename $f): $(compare -metric AE "$f" "current/$(basename $f)" null: 2>&1)"; done

Conclusion

compare is the tool to reach for when you need to not just see image differences but quantify them. A quick visual check is covered by the diff image; for automation you lean on -metric AE (counted pixels) or -metric RMSE/SSIM (similarity scores) and evaluate the exit code and stderr output. Budget some -fuzz to tolerate noise and lossy compression, otherwise every JPEG artefact trips a failure. Note that compare overwrites the named output file without asking, and on ImageMagick 7 prefer magick compare.