gdal_retile

What is gdal_retile?

gdal_retile.py takes one or more input rasters and retiles them into a regular grid of fixed-size tiles on disk, optionally with multiple pyramid levels of downsampled tiles. It is the go-to utility when you need chunked outputs for a tile server, a checkerboard of equally-sized GeoTIFFs, or a hierarchical pyramid of tiles arranged into level-numbered subdirectories.

gdal_retile.py [options] -targetDir <directory> <input_1> [<input_2>...]

Commonly used options:

• -targetDir <dir> — output directory
• -ps <tilewidth> <tileheight> — tile size in pixels (default 256×256)
• -overlap <pixels> — pixel overlap between adjacent tiles
• -levels <n> — build n pyramid levels (level 0 = native, 1 = 2x downsampled, …)
• -r <resampling> — resampling for pyramid levels
• -s_srs <CRS> / -tileIndex <name> / -tileIndexField <field> — optional tile-index vector output
• -csv <filename> — write a CSV index of tiles with their bounds
• -of <format> / -co <NAME>=<VALUE> / -ot <type> — driver, creation options, type
• -pyramidOnly — only build pyramid levels, assuming level 0 already exists

When would you use gdal_retile?

Use gdal_retile.py when downstream systems require fixed-size tiles on disk. Typical jobs: preparing a hierarchy of tiles for a legacy tile server that expects numbered folders per zoom level, chunking a huge mosaic into manageable pieces for distributed processing (gdal_retile.py -ps 4096 4096 -targetDir tiles/ big.tif), or producing a pyramid of downsampled tiles with -levels 4 for fast visualisation.

For web map serving via XYZ/TMS schemas, modern workflows often prefer gdal2tiles.py (which writes web-compatible tile pyramids) or just a COG served through a dynamic tile endpoint. gdal_retile.py remains relevant when the target is non-web (e.g. a catalog of uniform chunks, a processing pipeline that wants on-disk locality of reference) or when a legacy consumer depends on its folder layout.

FAQs

gdal_retile vs gdal2tiles — which should I use?

gdal_retile.py produces generic geo-referenced tiles in the source CRS, suitable for processing pipelines and catalog-style hosting. gdal2tiles.py produces XYZ/TMS web-ready tiles in Web Mercator with HTML viewer scaffolding. If you are targeting Leaflet, OpenLayers, or a raster tile server, gdal2tiles.py is usually the right choice.

Why does my pyramid directory structure look wrong?

-levels creates subdirectories 1/, 2/, etc. alongside the base level 0 tiles in targetDir. Each subdirectory holds halved-resolution tiles. If you expected a single-folder layout, use -pyramidOnly appropriately or drop -levels. Check the CSV index (-csv) for the exact file layout before consuming downstream.

Does gdal_retile overlap tiles?

Only if you pass -overlap <pixels>. The default is zero overlap, which is correct for tile-serving but can cause edge artefacts in analysis workflows that use focal operations per tile. A small overlap (e.g. 16 pixels) is a common choice for per-tile processing where kernel size is bounded.

Can I retile into COGs?

Yes — pass -of COG -co COMPRESS=DEFLATE. Each tile becomes its own COG with internal overviews, which is handy when building a tile catalog of cloud-optimised chunks for distributed access.