gdalbuildvrt

What is gdalbuildvrt?

gdalbuildvrt produces a GDAL Virtual Raster (VRT) — a small XML file that references one or more source rasters and presents them as a single dataset. A VRT has no pixels of its own; it just defines how source tiles or bands map into a virtual mosaic or stack. Any GDAL tool can then open the VRT as if it were one raster, which is the canonical way to mosaic thousands of tiles without writing terabytes of intermediate data.

gdalbuildvrt [options] <output.vrt> <source_1> [<source_2>...]

Commonly used options:

• -input_file_list <file> — read source filenames from a text file
• -separate — stack inputs as separate bands rather than tiling them spatially
• -resolution <highest|lowest|average|user> — strategy when sources have different resolutions
• -tr <xres> <yres> — explicit target resolution (use with -resolution user)
• -tap — snap pixel grid to target resolution (align to zero)
• -te <xmin> <ymin> <xmax> <ymax> — restrict output extent
• -srcnodata <value> / -vrtnodata <value> — declare source/output NoData values
• -addalpha — add an alpha band where gaps or NoData exist
• -b <band> — pick specific source bands
• -allow_projection_difference — permit CRS differences (use with care)

When would you use gdalbuildvrt?

Use a VRT whenever you need to treat many rasters as one without the I/O cost of physically mosaicking them. Typical jobs: combining hundreds of SRTM tiles into one DEM for a gdalwarp reprojection (gdalbuildvrt srtm.vrt srtm/*.hgt && gdalwarp -t_srs EPSG:3857 srtm.vrt srtm.tif), stacking Sentinel-2 single-band JP2s into a multispectral cube with -separate, or producing a quick preview across thousands of orthophoto tiles without writing a merged TIFF.

For very large mosaics, VRTs are the standard preprocessing step before gdalwarp — warping a VRT is dramatically faster than invoking warp on every tile individually, because GDAL streams only the pixels it needs. VRTs also edit well: you can open the XML and tweak source windows, NoData, or per-band scaling without rebuilding.

FAQs

When should I use -separate?

Use -separate when each input is a single band that you want stacked into a multi-band virtual dataset — the typical Sentinel-2 or Landsat layout, where each band ships as its own file. Without -separate, gdalbuildvrt assumes inputs share a band structure and places them spatially side by side.

How do I mosaic rasters with different resolutions?

Pass -resolution explicitly. highest uses the finest input pixel size (best quality, largest mosaic), lowest uses the coarsest (fastest), average splits the difference, and user with -tr lets you set the target. VRT itself does not resample — it just declares a target grid — so the actual resampling happens when a consumer reads the VRT.

Why do I get "projections of the source files are not the same" errors?

By default VRT refuses to mix CRSes because the file is a simple geotransform reference. Either reproject each source first with gdalwarp, or pass -allow_projection_difference to create the VRT and then warp it to a single CRS in one pass. The second approach is often the fastest path for large heterogenous datasets.

Are VRTs safe to move between machines?

A VRT stores paths to sources — relative by default, so a VRT plus its source folder travels fine if kept together. Absolute paths embedded by some workflows break on rename. Edit the <SourceFilename relativeToVRT="1"> entries in the XML to fix portability, or regenerate the VRT after any relocation.