gdaladdo

What is gdaladdo?

gdaladdo builds overviews (image pyramids) for raster datasets. Overviews are pre-computed downsampled copies at successive zoom levels stored inside the file (or in a sidecar .ovr) so map viewers and downstream tools can read coarse pyramids instead of the full-resolution grid. A 50,000 by 50,000 pixel orthomosaic without overviews is painful to pan in QGIS; the same file with a full pyramid scrolls instantly.

gdaladdo [options] <filename> [<level1> <level2> ...]

Commonly used options:

• -r <resampling> — resampling for overview generation (nearest, average, gauss, cubic, cubicspline, lanczos, bilinear, mode)
• -ro — read-only mode; write overviews to an external .ovr file
• -clean — remove existing overviews
• -b <band> — restrict to specific bands
• --config COMPRESS_OVERVIEW DEFLATE — compress overviews (GTiff)
• --config BIGTIFF_OVERVIEW IF_SAFER — allow BigTIFF overviews on large files
• --config GDAL_NUM_THREADS ALL_CPUS — parallelise overview build

Level list is a sequence of decimation factors (powers of two are conventional): 2 4 8 16 32.

When would you use gdaladdo?

Always build overviews on any raster larger than a few thousand pixels per side that will be viewed, served, or repeatedly read. Typical jobs: adding pyramids to a drone orthomosaic before delivery to a client, building overviews on a national elevation mosaic so a web viewer can serve tiles, or preparing a multispectral scene for fast quicklook rendering. Pair with gdalwarp creation options like -co COPY_SRC_OVERVIEWS=YES so warped outputs inherit pyramids from their source.

For delivery formats, build overviews internally: gdaladdo -r average ortho.tif 2 4 8 16 32. For read-only archives or when the source file format cannot embed overviews, use -ro to produce an ortho.tif.ovr sidecar. Use average or gauss on continuous imagery and nearest on categorical rasters to preserve class codes in downsampled levels.

FAQs

Which resampling method should I use for overviews?

Use average or gauss for continuous imagery like RGB orthos, satellite bands, and DEMs — they give clean visuals at zoomed-out levels. Use nearest for categorical rasters such as land cover, classified imagery, or any integer class codes, where invented intermediate values would corrupt the legend. cubic and lanczos look sharpest on photography but cost more CPU and can ring on high-contrast edges.

What overview levels should I pick?

Powers of two (2 4 8 16 32 64) are the standard because they line up with tile pyramid schemes used by web map viewers. Keep going until the coarsest level is a few hundred pixels wide — beyond that the overview adds storage with little viewing benefit. GDAL 3.2+ can also auto-pick levels if you pass no level list.

Internal or external overviews?

Internal (the default, written inside the file) is tidier and travels with the data. External .ovr files (enabled with -ro) are unavoidable for read-only inputs, for formats that cannot embed overviews (plain PNG, JPEG), or when you want to strip overviews later by deleting one file. COGs require internal overviews.

Why are my overviews huge?

Uncompressed overviews on a large raster can add tens of gigabytes. Set --config COMPRESS_OVERVIEW DEFLATE (or LZW, ZSTD) before running gdaladdo so the extra bands compress. For 8-bit imagery, --config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR --config INTERLEAVE_OVERVIEW PIXEL gives very small overviews suitable for web delivery.