GDALCOMPARE(1)

✨ NAME ✨

okay so, bestie, welcome to the GDAL manual 💖 this here is the page for GDALCOMPARE(1) — and it does exactly one iconic thing: compare two images 🦋

---

🌸 SYNOPSIS 🌸

gdalcompare [--help] [--help-general]
               [-dumpdiffs] [-skip_binary] [-skip_overviews]
               [-skip_geolocation] [-skip_geotransform]
               [-skip_metadata] [-skip_rpc] [-skip_srs]
               [-sds] <golden_file> <new_file>

---

💅 DESCRIPTION 💅

gdalcompare takes two datasets that GDAL supports, compares them, and reports the differences. And listen — it does not just yap at you on standard output. It also returns the difference count in its exit value. main character behaviour, honestly 👑

So what's getting checked? Image pixels, for sure, plus a whole bunch of metadata. And there's a byte-by-byte comparison happening too, which counts as one difference all on its own. So if the only thing you care about is that the data GDAL sees is identical, then a difference count of 1 — that one binary difference — should be considered totally acceptable. periodt 💯

NOTE: gdalcompare is a Python utility, and it's only available if the GDAL Python bindings are available. no bindings, no vibes 😭

--help — show this help message and exit, easy peasy 🎀

--help-general — gives you a brief usage message for the generic GDAL commandline options, and then exits. the generic options, not the slay-specific ones 💫

✨ the flags ✨

• -dumpdiffs — Added in version 3.8. Whether to output the difference in pixel content in a TIFF file in the current directory. yes bestie it literally writes you a whole TIFF of the diffs 🌈
• -skip_binary — Added in version 3.8. Whether to skip exact comparison of binary content. skipping the byte-by-byte, no problem 🫶
• -skip_overviews — Added in version 3.8. Whether to skip comparison of overviews. leave those overviews alone 🙈
• -skip_geolocation — Added in version 3.8. Whether to skip comparison of GEOLOCATION metadata domain. not today, geolocation 💀
• -skip_geotransform — Added in version 3.8. Whether to skip comparison of the geotransform matrix. matrices? never met her ✨
• -skip_metadata — Added in version 3.8. Whether to skip comparison of metadata. metadata who? don't know her 🎀
• -skip_rpc — Added in version 3.8. Whether to skip comparison of the Rational Polynomial Coefficients (RPC) metadata domain. rational polynomial coefficients, you are safe from this comparison 😌
• -skip_srs — Added in version 3.8. Whether to skip comparison of spatial reference systems (SRS). srs, we're ignoring you today bestie 💜
• -sds — if you pass this flag, the script compares all subdatasets that are part of the dataset. if you don't pass it, subdatasets are ignored. that's it, that's the deal 🦋

🥺 the arguments

• <golden_file> — the file that is considered correct. this one is referred to as the golden file. it's the reference, the blueprint, the moment 👑
• <new_file> — the file being compared to the golden file. this one is referred to as the new file. the challenger, if you will 🔥

---

okay and here's the part that makes me feral in a good way: the gdalcompare script — like all the other scripts, no cap — can also be called as a library from Python code:

from osgeo_utils import gdalcompare

The primary entry point is gdalcompare.compare_db(), which takes a golden gdal.Dataset and a new gdal.Dataset as its arguments and returns a difference count (excluding the binary comparison). And there's gdalcompare.compare_sds(), which you can use to compare subdatasets. library girly behaviour, we LOVE to see it 📚💖

---

🎯 RETURN STATUS CODE 🎯

The program returns status code 0 when it succeeds, and non-zero when there's an error. Important lil caveat: non-blocking errors that get emitted as warnings are still considered a successful execution. so a warning is not a fail, she's just talking 😭

---

🌈 EXAMPLES 🌈

Exhibit one, where things do not match:

gdalcompare -dumpdiffs N.tiff S.tiff; echo $?
Files differ at the binary level.
Band 1 checksum difference:
  Golden: 36694
  New:    40645
  Pixels Differing: 1509
  Maximum Pixel Difference: 255.0
  Wrote Diffs to: 1.tif
Differences Found: 2
2

Exhibit two, where a file is compared to its literal self and the vibe check is passed flawlessly:

gdalcompare N.tiff N.tiff; echo $?
Differences Found: 0
0

---

🫶 AUTHOR 🫶

Frank Warmerdam <warmerdam@pobox.com>

---

📜 COPYRIGHT 📜

1998-2026

---

and that's the whole page, bestie!! you ate this entire manual 💅 this was GDAL's GDALCOMPARE(1), dated Aug 18, 2026 — go forth and compare responsibly, mwah 🎀✨🦋