Compare Two Images with ImageMagick compare

Two screenshots look identical but the test says they are not: compare shows you exactly which pixels moved. This guide produces a visual difference image and a repeatable numeric check for two images. The examples use the installed ImageMagick 6 command, where compare resolves to compare-im6.q16, version 6.9.12-98 Q16, and it takes about ten minutes.

• You need: two readable image files and enough space for the output image.
• Privileges: none. The command reads the two inputs and writes only the output path you give it.

1. Confirm the installed command

Check the executable and package before relying on examples from another ImageMagick release:

$ command -v compare
/usr/bin/compare
$ readlink -f "$(command -v compare)"
/usr/bin/compare-im6.q16
$ compare --version
Version: ImageMagick 6.9.12-98 Q16 x86_64

Your build may have different delegates or a distribution revision, so keep the first two checks for diagnosing a result. The aliases compare, compare-im6 and compare-im6.q16 share the same installed manpage on this system.

2. Create a visual difference image

Run the comparison with two source paths followed by a new output path:

$ compare ORIGINAL.png RECONSTRUCTED.png difference.png

Replace the uppercase names with real files. The output is an image in the format chosen by its suffix. Bright or highlighted areas show where pixels differ, and quiet areas show little or no difference. The exact appearance depends on the input format, channels and comparison settings.

Verify that the output exists and is an image before you open it:

$ identify difference.png
difference.png PNG 1920x1080 1920x1080+0+0 8-bit sRGB ...

The dimensions and other fields will vary.

3. Measure exact pixel changes

When a script or test needs the answer, use an explicit metric. The absolute error metric reports the number of pixels that differ:

$ compare -metric AE ORIGINAL.png RECONSTRUCTED.png null:
0

Here null: is ImageMagick's null output, so no difference image is written. A result of 0 means no differing pixels under this comparison, and a positive value means some pixels differ. The metric goes to standard error, which is why it appears even though the command has no normal output.

Capture that stream explicitly when you save the measurement:

$ compare -metric AE ORIGINAL.png RECONSTRUCTED.png null: 2>pixel-count.txt
$ tr -d '\n' < pixel-count.txt
0

Treat the exit status as a separate signal. The manpage documents status 2 for an error, status 0 for similar images and a value between 0 and 1 for a non-similar result. A shell exposes fractional results as integer exit statuses, so never use the exit status as the measurement itself. Read the metric output, and handle status 2 as an operational failure.

4. Choose a metric for the question

Absolute error is a strict pixel-change count, but other metrics answer other questions. RMSE gives a magnitude of difference, while NCC measures correlation:

$ compare -metric RMSE ORIGINAL.png RECONSTRUCTED.png null: 2>&1
0 (0)
$ compare -metric NCC ORIGINAL.png RECONSTRUCTED.png null: 2>&1
1

Exact output varies with image content and channel depth. With RMSE, zero means no error. With NCC, the manpage defines one as the similar value. Never compare an RMSE threshold with an NCC threshold, and record the metric beside any stored result.

5. Check dimensions and alignment

Inspect both inputs before you blame a rendering defect:

$ identify ORIGINAL.png RECONSTRUCTED.png
ORIGINAL.png PNG 1920x1080 ...
RECONSTRUCTED.png PNG 1920x1080 ...

For a direct comparison, the command starts at the images' page offsets. If the sizes differ, the smaller image is aligned with the larger one and unmatched areas are treated as virtual pixels. That can change the metric, especially when one image has transparent or padded edges.

For a strict same-canvas test, reject unexpected geometry before comparing:

#!/bin/sh
set -eu

original='ORIGINAL.png'
reconstructed='RECONSTRUCTED.png'

original_size=$(identify -format '%wx%h' "$original")
reconstructed_size=$(identify -format '%wx%h' "$reconstructed")
if [ "$original_size" != "$reconstructed_size" ]; then
    printf 'size mismatch: %s versus %s\n' "$original_size" "$reconstructed_size" >&2
    exit 1
fi

compare -metric AE "$original" "$reconstructed" null: 2>pixel-count.txt

This check does not normalise, resize or alter either source. If different dimensions are expected, define the alignment and virtual-pixel policy for that test rather than silently accepting the default.

6. Find a matching subimage only when needed

If one image should occur inside another, add -subimage-search and choose a similarity metric:

$ compare -metric NCC -subimage-search LARGE.png TEMPLATE.png match.pfm 2>&1
... @ X,Y ...

The coordinates in the diagnostic identify the best match. Replace X,Y with the reported values when you read the output. The search is iterative, so it can be slow. It also respects image page offsets, so check those with identify if the location surprises you.

7. Diagnose the usual failures

An error status is not the same as a failed image match. Check the paths and file types first:

$ identify ORIGINAL.png RECONSTRUCTED.png
$ printf 'compare status: %s\n' "$?"
compare status: 0

Run each identify separately if you need to know which input failed. A missing file, unreadable file or malformed image needs fixing before a metric means anything. If ImageMagick reports a warning that should count as failure, the installed command also provides -regard-warnings.

When colour differences look unexpected, compare the intended channels explicitly, for example -channel RGB.