gdaladdo

Build overview images of a raster dataset using the "average" [r]esampling method

$ gdaladdo -r average [path/to/input.tif]

gdaladdo [-r {nearest|average|gauss|cubicspline|average_magphase|mode|rmsa}] [-ro] [-clean] [-oo NAME=VALUE]* datasetname [level1 [level2 ...]]

-r method
    Resampling method for overviews (default: nearest). Options: nearest, average, gauss, cubicspline, average_magphase, mode, rmsa.

-ro
    Write overviews to read-only .ovr file (safer for original dataset).

-clean
    Delete all existing overviews from the dataset.

-oo NAME=VALUE
    Format-specific open option for overview dataset ( repeatable ).

datasetname
    Path to input raster file (must support overviews).

level1 level2 ...
    Optional overview decimation levels (powers of 2, e.g., 2 4 8 16). Omitting auto-computes based on file size.

gdaladdo is a command-line utility from the GDAL (Geospatial Data Abstraction Library) suite designed to generate overview levels, also known as pyramids, for raster datasets. Overviews are reduced-resolution versions of the original raster that enable faster visualization and processing at smaller scales, essential for large imagery in GIS applications like QGIS, GRASS, or MapServer.

By precomputing these lower-resolution layers, gdaladdo avoids expensive on-the-fly resampling during zooming or panning, significantly improving performance. It supports various resampling methods to balance quality and speed, and overviews can be embedded directly in the source file (if supported) or stored in a separate .ovr sidecar file.

Typical workflow: Run after creating or translating a raster with gdal_translate. Specify levels as powers of 2 (e.g., 2, 4, 8, 16) matching display scales. Auto-levels can be inferred if none provided. Works with formats like GeoTIFF, JPEG2000, but support varies by driver.

Overview support is format/driver-dependent (e.g., GeoTIFF yes, PNG no). Requires write access unless -ro. Large files may consume significant disk space/time. Incompatible with compressed formats lacking pyramid support.

gdaladdo -r average image.tif 2 4 8 16
Builds average-resampled overviews at specified levels.

gdaladdo -clean -ro image.tif
Removes overviews, then adds new ones read-only.

gdaladdo image.tif
Auto-generates default overviews with nearest resampling.

Use gdalinfo to check existing overviews. Levels should cover expected zoom scales (e.g., web maps: 2-32). average best for continuous data; mode for categorical.

Introduced in early GDAL releases (~2004) as part of Frank Warmerdam's GDAL project. Evolved with GDAL 2.0+ for better resampling and driver support. Now maintained by OSGeo GDAL/OGR community, integral for geospatial workflows.

gdal_translate(1), gdalwarp(1), gdalinfo(1), gdalbuildvrt(1)