How to Compare Screenshots of Web Pages with ImageMagick

Use ImageMagick’s compare command to produce a visual diff and, when you choose a metric, a numeric measure of how two screenshots differ. First capture the same page state at matching dimensions; then run magick compare reference.png current.png difference.png. The reference image is your baseline and the current image is the capture you want to inspect.

ImageMagick compares image pixels, not page meaning. A changed-pixel count, average error, and structural similarity answer different questions, so select the metric that matches your regression check and inspect the visual diff before treating a score as a failure.

1. Prepare comparable screenshots

The comparison is only useful if the input images represent the same intended state. Before capture, try to keep these conditions consistent:

Viewport width and height, browser zoom, and device scale factor.
Scroll position and page offset.
Content state, including logged-in status, locale, test data, and open menus or dialogs.
Timing: wait for fonts, images, animations, and asynchronously loaded content to settle.

These are capture-workflow controls; ImageMagick compares the files it receives and does not control browser rendering. Check both image dimensions before interpreting a large difference. If dimensions differ, the images are aligned at their page offset (typically the top-left); unmatched areas can be treated as virtual pixels and affect the result. For visual regression checks, equal dimensions are usually easiest to reason about.

2. Create and inspect a visual difference image

With ImageMagick installed, save a diff image with:

magick compare reference.png current.png difference.png

Open difference.png to locate changed regions. The compare output annotates differences; it is a diagnostic image, not a replacement for looking at both original screenshots. The basic command creates the visual artifact. To also print a scalar metric, select one with -metric:

magick compare -metric AE reference.png current.png difference.png

ImageMagick writes metric output to the command’s diagnostic output stream. Capture that output in CI if you want to record or gate on a value. A nonzero command status can also indicate that differences were found, so a CI step should distinguish an expected diff result from an execution error rather than assuming every nonzero status means ImageMagick failed.

To calculate a metric without saving a diff image, use the special null: output:

magick compare -metric RMSE reference.png current.png null:

For diagnosis, it is often useful to generate the annotated output and calculate a metric separately: a score alone cannot tell you whether a difference is a full-page shift, one changed icon, or harmless rendering noise.

3. Choose a metric for the question

Metric	What it tells you	Useful when
`AE`	Absolute error: count of pixels that differ; affected by `-fuzz`.	You need a differing-pixel count under a chosen tolerance.
`PDC`	Count of pixels that differ; the options reference notes its relationship to `-fuzz`.	You want a pixel-count style result. Verify the exact metric behavior for your ImageMagick version and command.
`MAE`	Mean absolute error, a normalized average channel error.	You want average absolute channel difference.
`RMSE`	Root mean squared error, normalized; larger errors weigh more heavily than they do in a simple average.	You want an overall error score that gives more weight to large channel deviations.
`SSIM` / `DSSIM`	Structural similarity / dissimilarity measures.	You want a structural comparison rather than exact pixel equality. Confirm the interpretation for the chosen metric and version.
`NCC`	Normalized cross-correlation. ImageMagick documents similarity as 1 for NCC; for other metrics, zero difference is the similar case.	You are specifically comparing correlation and will interpret its direction correctly.

For exact change counts, use a pixel-count metric such as AE. For overall magnitude, consider MAE or RMSE. For structural similarity, use SSIM or DSSIM. No universal threshold makes a screenshot “the same”: establish a baseline using your own stable captures, record the metric and tolerance, and review the diff for localized regressions that an average could hide.

4. Tolerate small color differences with fuzz

The -fuzz option treats colors within a specified distance as equal for relevant comparisons. For example, use a 5% fuzz threshold with an absolute-error count:

magick compare -metric AE -fuzz 5% reference.png current.png difference.png

Fuzz can discount small differences, such as artifacts introduced by lossy JPEG encoding. It can also hide a meaningful small change. There is no universal browser-rendering fuzz value: tune it against the variability in your own captures, record it with the result, and inspect what disappears from the diff. Start with no fuzz when investigating an unexplained change.

5. Improve the readability of the diff

Use -highlight-color and -lowlight-color to choose how changed and unchanged regions appear in the compare output. For example:

magick compare -highlight-color red -lowlight-color white reference.png current.png difference.png

Another option is ImageMagick’s Difference composition, which subtracts the darker input color from the lighter and produces black where the colors match. A difference blend can make small changes look subtle; the ImageMagick usage guide demonstrates normalizing a difference image to make low-level changes easier to see. Treat a normalized visualization as a locator, not as a new numeric pass/fail metric.

6. Handle dimensions and unmatched pixels

If image sizes differ, first ask whether the capture itself is wrong: a different viewport, full-page length, or crop often explains the mismatch. Re-capture at matching dimensions when possible. If you intentionally need to compare different extents, ImageMagick’s compare:virtual-pixels define can limit comparison to authentic pixels:

magick compare -define compare:virtual-pixels=false -metric AE reference.png current.png difference.png

Consult the define’s documentation for exact behavior. Limiting unmatched virtual areas may be appropriate for a particular analysis, but it can conceal that one screenshot is missing content. Keep dimensions in the report and inspect the output whenever sizes differ.

7. A repeatable visual-regression workflow

Capture the reference and current page under the same viewport, scale, scroll position, and state.
Check dimensions and confirm both files open correctly.
Run magick compare to produce a diff image.
Run a named metric such as AE or RMSE and save its output with the build artifacts.
Review the highlighted regions. Separate broad layout movement from small isolated pixel noise.
If you use fuzz, record the value and inspect whether it hides a meaningful change.
Re-capture if fonts, animation, dynamic content, or delayed assets made the input states inconsistent.

For automated gates, define the metric, expected direction, tolerance, and image dimensions explicitly. Keep the reference image and diff artifact available so a failed comparison can be investigated instead of reduced to an unexplained number.

8. Troubleshooting

Symptom	Likely cause	What to do
`magick: command not found`	ImageMagick is not installed or its executable is not on `PATH`.	Install ImageMagick using the method for your operating system, then verify with `magick -version`. The official command-line tools page describes the available tools.
Images appear completely different	Viewport, scale, crop, scroll position, or page state changed; one capture may also be incomplete.	Compare dimensions and capture conditions first. Re-capture after fonts and delayed assets settle.
Large difference count from a small size mismatch	Unmatched areas contribute through virtual-pixel handling.	Use matching dimensions, or deliberately assess the documented `compare:virtual-pixels` setting and inspect the unmatched region.
Metric is printed but no difference file is created	The output was set to `null:`.	Use a filename such as `difference.png` when you need a visual artifact.
Small differences vanish after adding fuzz	The tolerance is broad enough to treat those color changes as equal.	Lower or remove fuzz, record the setting, and inspect the unfiltered comparison.
CI marks a comparison as a failed command	The command may have found a difference and returned a status your script treats as an execution failure.	Capture metric and diagnostic output, check the status semantics for your ImageMagick version, and make the pipeline handle “differences found” separately from missing files or invalid arguments.
Diff output is hard to see	Changes are small relative to the image or the chosen colors are low contrast.	Set highlight and lowlight colors, inspect the original pair, or normalize a difference visualization for diagnosis.

9. Performance, reliability, and cost

compare runs locally over the image files you provide. Work generally grows with the number of pixels being compared, so full-page images and high device-scale captures require more processing and memory than smaller viewports. Keep image dimensions and formats consistent, and avoid repeatedly creating unnecessary intermediate files in a large regression suite.

The reliability of the result depends on reliable inputs: dynamic content, late fonts, animation, and inconsistent test state can create noisy diffs. ImageMagick identifies image differences; it does not establish whether a visual change is a defect. Pair numeric checks with artifact review and stable capture conditions.

ImageMagick is software used locally for this workflow; the cited documentation does not specify a per-comparison service price. Your practical costs are the compute and storage for captures and artifacts, plus the engineering time spent stabilizing inputs and reviewing changes.

Or skip the browser setup

If you need the screenshots as well as the comparison, ScreenshotNeo is a website screenshot API and MCP server for developers. Its one-call API can return a PNG, JPEG, WebP, or PDF; see the API documentation. For example, save a capture of Stripe as WebP:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo accepts cookie or consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. All features are on every plan.

FAQ

Does a visual diff prove that the page is broken?

No. It identifies image changes. Review the changed region and decide whether the change is expected for your page and test state.

Should I use AE or RMSE?

Use AE when you want a count of changed pixels under the configured comparison tolerance. Use RMSE when you want a normalized overall error measure that gives larger channel differences more influence. They are not interchangeable.

Can I compare screenshots with different dimensions?

ImageMagick can align them and handle unmatched areas as virtual pixels, but the result may be harder to interpret. Matching dimensions is the clearest default; use the virtual-pixel define only when you understand the effect on the question you are asking.

Will fuzz remove all rendering noise safely?

No. Fuzz changes which color differences count as equal and can also suppress a real small change. Choose and record a value based on your captures, then inspect the resulting diff.