GDALTINDEX(1)

📦
version 3.13.3 · 11 versions
, in alpine 3.24, arch rolling, ubuntu stonking

✨ GDALTINDEX ✨

ok bestie sit down because we're doing the gdaltindex (1) page from the GDAL crew and it's a whole vibe. it builds a shapefile as a raster tileindex. yes. that. let's go 💅

🌸 SYNOPSIS 🌸

Usage: gdaltindex [--help] [--long-usage] [--help-general]
                  [-overwrite] [-recursive] [-filename_filter <val>]...
                  [-min_pixel_size <val>] [-max_pixel_size <val>]
                  [-of <output_format>] [-tileindex <field_name>]
                  [-write_absolute_path] [-skip_different_projection]
                  [-t_srs <srs_def>] [-src_srs_name <field_name>]
                  [-src_srs_format {AUTO|WKT|EPSG|PROJ}] [-lyr_name <name>]
                  [-lco <NAME>=<VALUE>]... [-gti_filename <filename>]
                  [-tr <xres> <yres>] [-te <xmin> <ymin> <xmax> <ymax>]
                  [-ot <datatype>] [-bandcount <val>] [-nodata <val>]...
                  [-colorinterp <val>]... [-mask] [-mo <name>=<value>]...
                  [-fetch_md <gdal_md_name> <fld_name> <fld_type>]... [--quiet]
                  <index_file> <file_or_dir>...

like, that's the whole menu. it's giving chef's kiss ✨

💖 DESCRIPTION 💖

okay so here's the tea 🫖: this program makes an OGR-supported dataset where every input raster file gets its own record — one attribute with the filename, and a polygon geometry outlining the raster. iconic.

and what's that output for? bestie it's literally built to be used with MapServer as a raster tileindex, or as input for the GTI driver. two careers, one dataset. main character energy fr fr 👑

TIP: Equivalent in new "gdal" command line interface: See gdal raster index.

no cap, that's the modern glow-up version. iykyk.

🎀 the options (part one of the saga)

  • --help — shows this help message and dips. bye 👋
  • --help-general — gives you a lil brief usage message for all the generic GDAL commandline options, then exits. the primer, the appetizer, the ✨preamble✨.
  • -q, --quiet — shuts up the progress messages and any other non-error output. no thoughts, head empty, just results 🤫
  • -overwrite — Added in version 3.9.

overwrites the tile index if it's already chillin' there. out with the old 📁

  • -recursive — Added in version 3.9.

decides whether directories you hand it in <file_or_dir> get explored recursively. like, do we go down into the subfolders or nah? 🦋

  • -filename_filter <val> — Added in version 3.9.

a pattern that the filenames inside the directories pointed at by <file_or_dir> have to follow to be let in. '*' is a wildcard that matches any number of any characters including none. '?' is a wildcard that matches exactly one character. and ngl, the comparisons are done in a case insensitive way. you can stack several filters too, no problem.

for example: -filename_filter "*.tif" -filename_filter "*.tiff" 🌈

  • -min_pixel_size <val> — Added in version 3.9.

the minimum pixel size, measured as geospatial extent per pixel (aka resolution), that a raster needs to have to make the cut. important: the pixel size gets evaluated after reprojection of its extent to the target SRS you set with -t_srs. so it's giving... postglow pixel math 💅

  • -max_pixel_size <val> — Added in version 3.9.

same situation but the ceiling — the maximum pixel size in geospatial extent per pixel (resolution) allowed for selection. also evaluated after reprojection to the target SRS from -t_srs. so it's giving... postglow pixel math but the other direction 🎀

  • -of <output_format> — the OGR format of your output tile index file. if you don't say anything, the format gets guessed from the extension. manifesting via file suffix fr.
  • -tileindex <field_name> — the name of the output field that holds the file path/location of the indexed rasters. default field name is location. it's literally called location by default, cute.
  • -write_absolute_path — stores the absolute path to the raster files in the tile index. by default, the raster filenames go in exactly as you typed them on the command line. lazy mode vs. meticulous mode, pick ur fighter 😌
  • -skip_different_projection — only files with the same projection as the files already in the tileindex get inserted (ya know, unless -t_srs is specified). by default it does not check projection at all and accepts everything. chaotic neutral default behavior, honestly 💀
  • -t_srs <target_srs> — geometries of the input files get transformed into whatever target coordinate reference system you want. default just makes simple rectangular polygons in the same CRS as the input rasters. keep it simple or remix it 🌍
  • -src_srs_name <field_name> — the name of the field where the SRS of each tile gets stored. you can use this field name as the value of the TILESRS keyword in MapServer. 🧚
  • -src_srs_format {AUTO|WKT|EPSG|PROJ} — the format each tile's SRS must be written in. types can be AUTO, WKT, EPSG, PROJ. this option should be used together with -src_srs_format. (yes, it says that. i'm just the messenger 📬)
  • -lyr_name <name> — the layer name to create/append to in the output tile index file. name ur layer bestie, give it an identity 🎀
  • -lco <NAME>=<VALUE> — Added in version 3.9.

layer creation option. format specific, so it depends on your format's whole deal. 💖

  • <index_file> — the name of the output file to create or append to. if the default dataset doesn't already exist, it gets created; otherwise it appends to the existing one. glow-up or sequel, ur call 🔥
  • <file_or_dir> — the input GDAL raster files. can be multiple files, separated by spaces. wildcards are allowed too. it stores the file locations in the same style as you specified them here — unless you also used the -write_absolute_path option, in which case, absolute it is.

Starting with GDAL 3.9, this can also be a directory name. and -recursive works here too, to recurse down into sub-directories. 🦋

you can also use the generic option --optfile filelist.txt to specify a list of source files. list-in-a-file girlies rise up 📝

🌈 OPTIONS SPECIFIC TO USE BY THE GDAL GTI DRIVER 🌈

okay so gdaltindex can also generate a tile index that's built for the GTI driver. and there are two ways to play this:

  • either you use a vector tile index generated by gdaltindex directly as the input of the GTI driver,
  • or you generate a small XML .gti wrapper file, which is easier with non-file-based formats like databases, or for vector formats that don't support setting layer metadata items.

formats that do support layer metadata? for example GeoPackage (-of GPKG), FlatGeoBuf (-of FlatGeoBuf) or PostGIS (-of PG). slay.

setting -tr and -ot is recommended so the GTI driver doesn't have to sit there and deduce them by opening the first tile in the index. efficiency queen 👑 and if your tiles have a nodata or a mask band, you should set -nodata and -mask too.

in a GTI context, the extent of all tiles referenced in the tile index must be expressed in a single SRS. so if your input tiles might have different SRS, you gotta specify either -t_srs or -skip_different_projection. no mixing, bestie, that's the rule 🚨

  • -gti_filename <name> — Added in version 3.9.

the filename of the XML Virtual Tile Index file to generate, which can be used as an input for the GDAL GTI / Virtual Raster Tile Index driver. super handy when you're writing the tile index in a vector format that doesn't support writing layer metadata items. ✨

  • -tr <xres> <yres> — Added in version 3.9.

target resolution in SRS unit per pixel.

this gets written into the XML Virtual Tile Index if -gti_filename is specified, or as the RESX and RESY layer metadata items for formats that support layer metadata. 📐

  • -te <xmin> <ymin> <xmax> <ymax> — Added in version 3.9.

target extent in SRS unit.

written into the XML Virtual Tile Index if -gti_filename is specified, or as the MINX, MINY, MAXX and MAXY layer metadata items for formats that support layer metadata. 📏

  • -ot <datatype> — Added in version 3.9.

data type of the tiles of the tile index: Byte, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float32, Float64, CInt16, CInt32, CFloat32 or CFloat64.

written into the XML Virtual Tile Index if -gti_filename is specified, or as the DATA_TYPE layer metadata item for formats that support layer metadata. 🧬

  • -bandcount <val> — Added in version 3.9.

number of bands of the tiles of the tile index.

written into the XML Virtual Tile Index if -gti_filename is specified, or as the BAND_COUNT layer metadata item for formats that support layer metadata.

a mix of tiles with N and N+1 bands is allowed, as long as the color interpretation of the (N+1)th band is alpha. in that situation, the N+1 value must be written as the band count. so like, know the rules before u f around 💅

and heads up: if -nodata or -colorinterp are specified and have multiple values, the band count is also inferred from that number. sneaky inference, love that for us.

  • -nodata <val>[,<val>...] — Added in version 3.9.

nodata value of the tiles of the tile index.

written into the XML Virtual Tile Index if -gti_filename is specified, or as the NODATA layer metadata item for formats that support layer metadata. 🕳️

  • -colorinterp <val>[,<val>...] — Added in version 3.9.

color interpretation of the tiles of the tile index: red, green, blue, alpha, gray, undefined.

written into the XML Virtual Tile Index if -gti_filename is specified, or as the COLOR_INTERPRETATION layer metadata item for formats that support layer metadata. 🎨

  • -mask — Added in version 3.9.

whether the tiles in the tile index have a mask band.

written into the XML Virtual Tile Index if -gti_filename is specified, or as the MASK_BAND layer metadata item for formats that support layer metadata. 👺

  • -mo <KEY>=<VALUE> — Added in version 3.9.

write an arbitrary layer metadata item, for formats that support layer metadata. this option may be repeated. stack 'em up 🧁

NOTE: This option cannot be used together -gti_filename
  • -fetch_md <gdal_md_name> <fld_name> <fld_type> — Added in version 3.9.

fetches a metadata item from the raster tile and writes it as a field in the tile index. like grabbing receipts and filing them 📂✨

<gdal_md_name> should be the name of the raster metadata item. {PIXEL_SIZE} may be used as a special name to indicate the pixel size.

<fld_name> should be the name of the field to create in the tile index.

<fld_type> should be the name of the type to create. one of String, Integer, Integer64, Real, Date, DateTime.

this option may be repeated.

for example: -fetch_md TIFFTAG_DATETIME creation_date DateTime

✨ EXAMPLES ✨

Like, bestie, here's where it gets fun. Actual things you can type. 🎀

💖 Example 1

Say you wanna produce a shapefile (doq_index.shp) that has a record for every single image the utility found chilling in the doq folder 📂. Each one of those records is holding info that points to where the image lives and a bounding rectangle shape showing that image's bounds. Iconic behavior, honestly.

gdaltindex doq_index.shp doq/*.tif

🦋 Example 2

Okay so literally the same command as before, except now we're making a GeoPackage instead of a Shapefile. A glow-up, if you will ✨

gdaltindex -of GPKG doq_index.gpkg doq/*.tif

🌸 Example 3

The -t_srs option can also be used to transform all your input rasters into the same output projection. Yes, all of them. Matching. Coordinated. Slay 🫶

gdaltindex -t_srs EPSG:4326 -src_srs_name src_srs tile_index_mixed_srs.shp *.tif

💅 Example 4

Now we're making a tile index from files that are listed inside a text file 📄, with metadata suitable for use by the GDAL GTI / Virtual Raster Tile Index driver. Look at us, being all fancy.

gdaltindex tile_index.gti.gpkg -ot Byte -tr 60 60 -colorinterp Red,Green,Blue --optfile my_list.txt

👑 RETURN STATUS CODE

The program returns status code 0 when everything goes right, and non-zero when there's an error. And listen — non-blocking errors that get emitted as warnings are still considered a successful execution 💀 so don't panic if you see a little warning, okay?

🌈 C API

Not just a command-line moment, no ma'am — this utility is also callable from C with GDALTileIndex(). Tell your C friends 🫶

⭐ SEE ALSO

  • Common options for raster programs, for all the other command-line options you might want — and in particular the --optfile switch, which can be used to specify a list of input datasets.

💜 AUTHOR

Frank Warmerdam <warmerdam@pobox.com> — the icon, the legend, the moment 👑

1998-2026

And that's the whole page, bestie 💖 This one's GDALTINDEX(1), dated Aug 18, 2026 — go forth and index your tiles, you absolute main character 🦋✨

📦 where this page comes from