gdaltindex

What is gdaltindex?

gdaltindex scans a list of raster files and builds a vector tile index — a Shapefile, GeoPackage, or other OGR format containing one polygon per raster with an attribute recording the path to that raster. The resulting index is a raster catalog: MapServer, QGIS, and other viewers can use it to serve thousands of tiles as a single virtual layer, only reading the individual files that intersect the current view.

gdaltindex [options] <index_file> <raster_file> [<raster_file>...]

Commonly used options:

• -f <format> — output vector driver (ESRI Shapefile, GPKG, GeoJSON, …)
• -tileindex <field> — attribute name holding the tile path (default location)
• -write_absolute_path — store absolute paths rather than relative
• -skip_different_projection — skip rasters whose CRS does not match the first
• -t_srs <CRS> — project footprints into this CRS; requires -src_srs_name to record source CRS
• -src_srs_name <field> / -src_srs_format <format> — record per-raster source CRS
• -lyr_name <name> — output layer name (non-Shapefile)

When would you use gdaltindex?

Use gdaltindex whenever a raster dataset is delivered as many tiles and you want to treat them as a single logical layer. Typical jobs: building a national aerial imagery mosaic index so MapServer can serve only the tiles that intersect each map request, producing a DEM tile index for a watershed analysis pipeline, or creating a QA layer that shows tile footprints on a background map before mosaicking.

The output is also handy input for gdalbuildvrt -input_file_list when you want to mosaic after indexing, or for ogr2ogr if you need to enrich the index with additional attributes. Example: gdaltindex -f GPKG tiles.gpkg tiles/*.tif produces a GeoPackage with one polygon per tile plus a location field pointing at each file.

FAQs

gdaltindex vs gdalbuildvrt — which should I use?

They solve different problems. gdaltindex produces a vector footprint catalog that viewers read on demand; tiles may have different CRSes if you use -t_srs. gdalbuildvrt produces a virtual raster that references the tiles as one seamless image, better for analysis pipelines. Use tindex for map serving, buildvrt for processing.

How do I handle tiles in different projections?

Pass -t_srs for a common footprint CRS and add -src_srs_name source_srs so each row records its native CRS. Consumers like MapServer can then reproject on the fly. Without these flags, mixing CRSes in one index silently corrupts spatial queries.

Why are my paths broken after moving the index?

By default gdaltindex stores paths relative to the index file's location. Move the index and the paths break. Either keep the folder layout intact, regenerate the index, or pass -write_absolute_path at creation time for portable (but machine-specific) references.

Can I append to an existing index?

Yes — running gdaltindex against an existing index file will append new tiles as long as the output format supports update. Shapefile and GeoPackage both work. Pass only the new files on the command line to avoid duplicate rows.