gdalcompare

What is gdalcompare?

gdalcompare.py diffs two raster datasets and reports every difference — dimensions, band structure, CRS, geotransform, metadata, overviews, and pixel-level checksums. It is the standard regression-test tool for GDAL: use it to confirm that a processing change did not silently perturb outputs, or to catch unintended metadata drift after a round-trip through a pipeline.

gdalcompare.py [-dumpdiffs] [-skip_binary] [-skip_overview] [-skip_geolocation] [-skip_geotransform] [-skip_metadata] [-skip_rpc] [-skip_srs] <golden_file> <new_file>

Commonly used flags:

• -dumpdiffs — print per-band difference statistics
• -skip_binary — do not checksum pixel data (header-only compare)
• -skip_overview — skip overview comparison
• -skip_geolocation — skip geolocation arrays
• -skip_geotransform — skip geotransform comparison
• -skip_metadata — skip metadata domains
• -skip_rpc — skip RPC metadata
• -skip_srs — skip CRS comparison

When would you use gdalcompare?

Use gdalcompare.py in any pipeline where output fidelity matters. Typical jobs: regression tests on a nightly processing job to confirm outputs are bit-identical to a golden reference (gdalcompare.py golden.tif new.tif), verifying that a round-trip through gdal_translate or gdalwarp did not drop metadata or add unintended overviews, and spot-checking that a refactor to a Python-GDAL script still produces matching rasters.

Exit code is non-zero if differences are found, making it trivial to integrate into CI. For heavy processing pipelines, pair -skip_metadata with pixel checksum comparison to ignore harmless metadata churn (driver-version strings, timestamps) while still catching any pixel drift.

FAQs

How is gdalcompare different from a plain file diff?

A binary diff or cmp fails on any byte difference — including harmless ones like embedded timestamps, GDAL version strings, or driver-specific metadata that change between builds. gdalcompare.py is structural: it checks dimensions, CRS, pixel checksums, and metadata fields independently and reports which category differs. That lets you ignore irrelevant differences while still catching real data changes.

What exit code does gdalcompare return?

The exit code is the number of differences detected (capped to an unsigned byte). Zero means identical to whatever depth you compared. CI jobs can simply test $? -ne 0 to fail on any divergence.

Can I compare only pixel contents and ignore metadata?

Yes — combine -skip_metadata -skip_srs -skip_geotransform -skip_overview -skip_rpc to focus on pixel checksums. Useful when refactoring a pipeline produces identical pixels but rewrites metadata in a reorganised way.

Does gdalcompare show per-pixel differences?

Not in full. It reports band-level checksum differences and, with -dumpdiffs, per-band summary statistics. For a true per-pixel diff raster, use gdal_calc.py --calc="A-B" -A old.tif -B new.tif --outfile=diff.tif and inspect the result in your GIS.