GDALBUILDVRT(1)

📦

version 3.13.3 · 11 versions

3.13.3 · alpine 3.24, arch rolling, ubuntu stonking (latest)
3.11.3 · opensuse-leap 16.0
3.11.5 · fedora 43
3.11.4 · fedora 43
3.4.1 · ubuntu jammy
3.12.4 · fedora 44
3.12.3 · fedora 44
3.8.4 · ubuntu noble
3.6.2 · debian bookworm
3.12.2 · ubuntu resolute
3.10.3 · centos-stream 10, centos-stream 9, debian trixie, ubuntu questing

, in alpine 3.24, arch rolling, ubuntu stonking

gdalbuildvrt(1) GDAL

okay bestie, this one came out of the GDAL manual, section 1, and it is genuinely one of the most useful little tools out there — it's the mosaic-maker 💖

✨ NAME ✨

gdalbuildvrt — Builds a VRT from a list of datasets. that's the whole vibe, short and iconic 🎀

🦋 SYNOPSIS 🦋

gdalbuildvrt [--help] [--long-usage] [--help-general]
             [--quiet]
             [[-strict]|[-non_strict]]
             [-tile_index <field_name>]
             [-resolution user|average|common|highest|lowest|same]
             [-tr <xres> <yres>] [-input_file_list <filename>]
             [[-separate]|[-pixel-function <function>]]
             [-pixel-function-arg <NAME>=<VALUE>]...
             [-allow_projection_difference] [-sd <n>] [-tap]
             [-te <xmin> <ymin> <xmax> <ymax>] [-addalpha] [-b <band>]...
             [-hidenodata] [-overwrite]
             [-srcnodata "<value>[ <value>]..."]
             [-vrtnodata "<value>[ <value>]..."] [-a_srs <srs_def>]
             [-r nearest|bilinear|cubic|cubicspline|lanczos|average|mode]
             [-oo <NAME>=<VALUE>]... [-co <NAME>=<VALUE>]...
             [-ignore_srcmaskband]
             [-nodata_max_mask_threshold <threshold>]
             <vrt_dataset_name> [<src_dataset_name>]...

💅 DESCRIPTION 💅

okay so, this program builds a raster VRT (Virtual Dataset) that is a mosaic of a list of input GDAL datasets. the list of input GDAL datasets can be specified at the end of the command line, put in a text file (one filename per line) for very long lists, or it can be a MapServer tileindex (see the gdaltindex utility). if you're using a tile index, all entries in the tile index will be added to the VRT. all of them. no skips 🫶

NOTE: starting with GDAL 3.9, for virtual mosaics with a very large number of source rasters (hundreds of thousands of source rasters, or more), it is advised to use the gdaltindex utility to generate a tile index compatible with the GTI driver. like bestie, at that scale just do it this way, trust 💀

TIP: equivalent in new "gdal" command line interface: see gdal raster mosaic and gdal raster stack. ✨

with -separate, each input goes into a separate band in the VRT dataset. otherwise, the files are considered as source rasters of a larger mosaic and the VRT file has the same number of bands as the input files. 🌈

if one GDAL dataset is made of several subdatasets and has 0 raster bands, all the subdatasets will be added to the VRT rather than the dataset itself. lowkey convenient 🎀

gdalbuildvrt does some checks to ensure that all files that will be put in the resulting VRT have similar characteristics: number of bands, projection, color interpretation, etc. if not, files that do not match the common characteristics will be skipped unless -strict is used. (this is only true in the default mode, and not when using the -separate option.) so yeah, silent skipping is a real thing here, pay attention 👀

starting with GDAL 3.12, a function (e.g., min, mean, median) can be specified (-pixel-function) to calculate pixel values from overlapping inputs. if no function is specified, or in earlier versions, the order of the input list is used to determine priority. files that are listed at the end are the ones from which the content will be fetched. note that nodata will be taken into account to potentially fetch data from lower-priority datasets, but currently, alpha channel is not taken into account to do alpha compositing (so a source with alpha=0 appearing on top of another source will override its content). this might be changed in later versions. 💀

ok now, the options 💖

--help — show this help message and exit. the classic 🫶
--help-general — gives a brief usage message for the generic GDAL commandline options and exit.
-q, --quiet — suppress progress messages and other non-error output. for when you want it silent and mysterious ✨
-tileindex <field_name> — use the specified value as the tile index field, instead of the default value which is 'location'. (heads up bestie, the synopsis up there spells it -tile_index — that's literally what the page says, both spellings are in here 💅)
-resolution {highest|lowest|average|user|same} — in case the resolution of all input files is not the same, the -resolution flag lets you control the way the output resolution is computed. pick your fighter:
- highest will pick the smallest values of pixel dimensions within the set of source rasters.
- lowest will pick the largest values of pixel dimensions within the set of source rasters.
- average is the default and will compute an average of pixel dimensions within the set of source rasters.
- user must be used in combination with the -tr option to specify the target resolution.
- same (added in GDAL 3.11) checks that all source rasters have the same resolution and errors out when this is not the case.
- common (added in GDAL 3.11) determines the greatest common divisor of the source pixel dimensions, e.g. 0.2 for source pixel dimensions of 0.4 and 0.6. math girlie behaviour 🧚
-tr <xres> <yres> — set target resolution. the values must be expressed in georeferenced units. both must be positive values. specifying these values is of course incompatible with highest|lowest|average values for the -resolution option. don't fight it, they just can't coexist 😭
-tap — (target aligned pixels) align the coordinates of the extent of the output file to the values of the -tr, such that the aligned extent includes the minimum extent. alignment means that xmin / resx, ymin / resy, xmax / resx and ymax / resy are integer values. satisfying fr fr ⭐
-te <xmin> <ymin> <xmax> <ymax> — set georeferenced extents of VRT file. the values must be expressed in georeferenced units. if not specified, the extent of the VRT is the minimum bounding box of the set of source rasters. pixels within the extent of the VRT but not covered by a source raster will be read as valid pixels with a value of zero unless a NODATA value is specified using -vrtnodata or an alpha mask band is added with -addalpha. so yes, you get sneaky zeros unless you say otherwise 🫶
-addalpha — adds an alpha mask band to the VRT when the source raster have none. mainly useful for RGB sources (or grey-level sources). the alpha band is filled on-the-fly with the value 0 in areas without any source raster, and with value 255 in areas with source raster. the effect is that a RGBA viewer will render the areas without source rasters as transparent and areas with source rasters as opaque. this option is not compatible with -separate. transparent where there's nothing, iconic 🌸
-hidenodata — even if any band contains nodata value, giving this option makes the VRT band not report the NoData. useful when you want to control the background color of the dataset. by using along with the -addalpha option, you can prepare a dataset which doesn't report nodata value but is transparent in areas with no data. sneaky AND useful 💅
-srcnodata "<value>[ <value>]..." — set nodata values for input bands (different values can be supplied for each band). if more than one value is supplied all values should be quoted to keep them together as a single operating system argument. if the option is not specified, the intrinsic nodata settings on the source datasets will be used (if they exist). the value set by this option is written in the NODATA element of each ComplexSource element. use a value of None to ignore intrinsic nodata settings on the source datasets.
-ignore_srcmaskband — added in version 3.3.

starting with GDAL 3.3, if a source has a mask band (internal/external mask band, or alpha band), a <ComplexSource> element is created by default with a <UseMaskBand>true</UseMaskBand> child element, to instruct the VRT driver to use the mask band of the source to mask pixels being composited. this is a generalization of the NODATA element. when specifying the -ignore_srcmaskband option, the mask band of sources will not be taken into account, and in case of overlapping between sources, the last one will override previous ones in areas of overlap. 🦋

-nodata_max_mask_threshold <threshold> — added in version 3.9.

insert a <NoDataFromMaskSource> source, which replaces the value of the source with the value of -vrtnodata (or 0 if not specified) when the value of the mask band of the source is less or equal to the threshold. this is typically used to transform a R,G,B,A image into a R,G,B one with a NoData value. glow-down but make it data 💖

-b <band> — select an input <band> to be processed. bands are numbered from 1. if input bands not set all bands will be added to the VRT. multiple -b switches may be used to select a set of input bands. collect them all ✨
-sd <n> — if the input dataset contains several subdatasets, use a subdataset with the specified number (starting from 1). this is an alternative to giving the full subdataset name as an input to the utility. short and sweet 🌈
-vrtnodata "<value>[ <value>]..." — set nodata values at the VRT band level (different values can be supplied for each band). if more than one value is supplied, all values should be quoted to keep them together as a single operating system argument (Example 4). if the option is not specified, intrinsic nodata settings on the first dataset will be used (if they exist). the value set by this option is written in the NoDataValue element of each VRTRasterBand element. use a value of None to ignore intrinsic nodata settings on the source datasets.
-separate — place each input file into a separate band. see Example 3. contrary to the default mode, it is not required that all bands have the same datatype. this option is mutually exclusive with -pixel-function. pick one bestie, you can't have both 😭

starting with GDAL 3.8, all bands of each input file are added as separate VRT bands, unless -b is specified to select a subset of them. before GDAL 3.8, only the first band of each input file was placed into a new VRT band, and -b was ignored. lowkey a glow-up patch 💅

-pixel-function — specify a function name to calculate a value from overlapping inputs. for a list of available pixel functions, see Built-in Pixel Functions. if no function is specified, values will be taken from the last overlapping input. this option is mutually exclusive with with -separate. (yes, the double "with with" is straight from the page, we love a typo moment 🙈)

added in version 3.12.

-pixel-function-arg — specify an argument to be provided to a pixel function, in the format <NAME>=<VALUE>. multiple arguments may be specified by repeating this option.

added in version 3.12. 🎀

-allow_projection_difference — when this option is specified, the utility will create a VRT even if the input datasets do not have the same projection. Note: this does not mean that they will be reprojected. their projection will just be ignored. reading that carefully bestie, ignoring ≠ fixing 💀

👇 more below, keep scrolling 💖

-a_srs <srs_def> — okay bestie, this one lets you override the projection for the output file ✨. The <srs_def> can be literally any of the usual GDAL/OGR forms: complete WKT, PROJ.4, EPSG:n, or even a file that contains the WKT. Important though — no reprojection is done. It's giving "cosmetic label change" not "glow up transformation", iykyk 💅
-r {nearest|bilinear|cubic|cubicspline|lanczos|average|mode} — pick your resampling algorithm, queen 👑. The options are nearest, bilinear, cubic, cubicspline, lanczos, average, and mode. And nearest is the default, so if you don't say anything she just goes with nearest 💖
-oo <NAME>=<VALUE> — dataset open option (and yes it's format-specific, so check whatever format you're working with) 🦋
-co <NAME>=<VALUE> — specify a VRT driver creation option. Added in version 3.10. ⭐
-input_file_list <filename> — point her at a text file and she'll read it, one input filename per line 📝. Peep Example 2 below for the full vibe.
-q — disables the progress bar on the console. For the girlies who want the silence, no notes 💀
-overwrite — overwrites the VRT if it already exists. Lowkey ruthless but we respect it 🔥
-strict — turns warnings into failures 😭. Heads up: this is mutually exclusive with -non_strict — you can't have both. Also -non_strict is the default, so this is you actively choosing violence. Added in version 3.4.2.
-non_strict — skips source datasets that have issues with warnings, and just keeps on processing 🌈. This is the default, she's chill like that. Added in version 3.4.2.
-write_absolute_path — Added in version 3.12.0. Enables writing the absolute path of the input datasets. By default though, input filenames get written in a relative way with respect to the VRT filename (when possible) 🎀

💖 EXAMPLES 💖

✨ Example 1: Make a virtual mosaic from all TIFF files contained in a directory

gdalbuildvrt doq_index.vrt doq/*.tif

✨ Example 2: Make a virtual mosaic from files whose name is specified in a text file

gdalbuildvrt -input_file_list my_list.txt doq_index.vrt

✨ Example 3: Make a RGB virtual mosaic from 3 single-band input files

gdalbuildvrt -separate rgb.vrt red.tif green.tif blue.tif

✨ Example 4: Make a virtual mosaic with blue background colour (RGB: 0 0 255)

gdalbuildvrt -hidenodata -vrtnodata "0 0 255" doq_index.vrt doq/*.tif

🌟 RETURN STATUS CODE 🌟

The program returns status code 0 in case of success, and non-zero in case of error. Except — and this is the important lil footnote — non-blocking errors that get emitted as warnings are still considered a successful execution 🫶. So warning ≠ flop, got it?

🧚 C API 🧚

This utility is also callable from C with GDALBuildVRT(). Slay, she's bilingual 💅

👑 AUTHOR 👑

Even Rouault <even.rouault@spatialys.com>

🌸 COPYRIGHT 🌸

1998-2026

And that's the whole page, bestie 💖 This one's from Aug 18, 2026, living in the GDALBUILDVRT(1) era, with copyright dating all the way back to 1998 and running through 2026. Go build some virtual rasters, you main character 🦋✨

📦 where this page comes from

alpine 3.24: gdal-doc 3.13.3-r0 · MIT
arch rolling: gdal 3.13.3-6 · MIT
ubuntu stonking: gdal-bin 3.13.3+dfsg-1ubuntu4 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms