gdalchecksum

What is gdalchecksum?

gdalchecksum.py reports a per-band checksum for a raster dataset. The checksum is a deterministic hash of pixel values (not of the encoded file bytes), which makes it useful for detecting changes in pixel content across format conversions, re-encoding, or processing passes — two rasters with identical pixels will produce identical checksums regardless of compression or tile layout.

gdalchecksum.py [-b <band>]... [-srcwin <xoff> <yoff> <xsize> <ysize>] <filename>

Commonly used options:

• -b <band> — restrict to specific bands (repeatable)
• -srcwin <xoff> <yoff> <xsize> <ysize> — checksum only a pixel window

Output is one integer per band, printed to stdout.

When would you use gdalchecksum?

Use gdalchecksum.py in any QA workflow where you need a compact comparison of pixel contents. Typical jobs: verifying that a gdal_translate from GeoTIFF to COG preserved pixels exactly (same checksums before and after), writing unit tests that assert stable output pixel values, or generating fingerprints in a dataset catalogue so you can detect accidental modifications.

Because the checksum is computed on decoded pixels, it is invariant to compression, tiling, overview presence, and most metadata. This is precisely what makes it a useful "did the pixels actually change?" probe — a file-level sha256sum catches everything including harmless repacking, whereas gdalchecksum.py catches only real pixel-value change.

FAQs

Is the checksum a secure cryptographic hash?

No. GDAL's checksum is a fast, non-cryptographic 16-bit fold designed to detect accidental differences. Different pixel values can coincidentally produce the same checksum, though in practice collisions are rare for whole-raster comparisons. For security-grade integrity, use sha256sum on the file bytes in addition.

How does gdalchecksum compare to gdalcompare?

gdalchecksum.py prints one integer per band — cheap and scriptable. gdalcompare.py performs a full structural diff (dimensions, CRS, metadata, overviews, pixels) and returns a count of differences. Use checksum for fast pipeline assertions ("did these bands change?"); use compare for thorough regression testing.

Can I checksum only part of a raster?

Yes — pass -srcwin <xoff> <yoff> <xsize> <ysize> to restrict the checksum to a pixel window. Useful for testing that a specific region was modified while another remained intact, or for computing fingerprints on tile-by-tile subsets of a huge mosaic.

Why do I get the same checksum for different files?

If the files have identical pixel contents (but different compression, tiling, metadata, or format) the checksums should match — that is the tool's purpose. If they truly differ in pixels and still collide, you have hit a rare checksum collision; use gdal_calc.py --calc="A-B" to compute a difference raster and inspect actual values.