GDALBUILDVRT(1) GDAL GDALBUILDVRT(1)
gdalbuildvrt - Builds a VRT from a list of datasets.
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>]...
This program builds a 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 using a tile index, all
entries in the tile index will be added to the VRT.
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.
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.
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)
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.
--help Show this help message and exit
--help-general
Gives a brief usage message for the generic GDAL commandline
options and exit.
-tileindex <field_name>
Use the specified value as the tile index field, instead of
the default value which is 'location'.
-resolution {highest|lowest|average|user|same}
In case the resolution of all input files is not the same, the
-resolution flag enables the user to control the way the
output resolution is computed.
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.
-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 -resolution option.
-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.
-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.
-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.
-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.
-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.
-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.
-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.
-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.
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.
-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.
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.
-a_srs <srs_def>
Override the projection for the output file. The <srs_def>
may be any of the usual GDAL/OGR forms, complete WKT, PROJ.4,
EPSG:n or a file containing the WKT. No reprojection is done.
-r {nearest|bilinear|cubic|cubicspline|lanczos|average|mode}
Select a resampling algorithm. Nearest is the default
-oo <NAME>=<VALUE>
Dataset open option (format-specific)
-co <NAME>=<VALUE>
Specify a VRT driver creation option.
Added in version 3.10.
-input_file_list <filename>
Specify a text file with an input filename on each line. See
Example 2.
-q Disable the progress bar on the console
-overwrite
Overwrite the VRT if it already exists.
-strict
Turn warnings as failures. This is mutually exclusive with
-non_strict, the latter which is the default.
Added in version 3.4.2.
-non_strict
Skip source datasets that have issues with warnings, and
continue processing. This is the default.
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, input filenames are written in a relative way with
respect to the VRT filename (when possible).
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
This utility is also callable from C with GDALBuildVRT().
Even Rouault <even.rouault@spatialys.com>
1998-2026
March 20, 2026 GDALBUILDVRT(1)
NAME
gdalbuildvrt - Builds a VRT from a list of datasets.
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
This program builds a 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 using a tile index, all
entries in the tile index will be added to the VRT.
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.
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.
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)
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.
--help Show this help message and exit
--help-general
Gives a brief usage message for the generic GDAL commandline
options and exit.
-tileindex <field_name>
Use the specified value as the tile index field, instead of
the default value which is 'location'.
-resolution {highest|lowest|average|user|same}
In case the resolution of all input files is not the same, the
-resolution flag enables the user to control the way the
output resolution is computed.
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.
-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 -resolution option.
-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.
-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.
-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.
-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.
-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.
-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.
-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.
-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.
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.
-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.
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.
-a_srs <srs_def>
Override the projection for the output file. The <srs_def>
may be any of the usual GDAL/OGR forms, complete WKT, PROJ.4,
EPSG:n or a file containing the WKT. No reprojection is done.
-r {nearest|bilinear|cubic|cubicspline|lanczos|average|mode}
Select a resampling algorithm. Nearest is the default
-oo <NAME>=<VALUE>
Dataset open option (format-specific)
-co <NAME>=<VALUE>
Specify a VRT driver creation option.
Added in version 3.10.
-input_file_list <filename>
Specify a text file with an input filename on each line. See
Example 2.
-q Disable the progress bar on the console
-overwrite
Overwrite the VRT if it already exists.
-strict
Turn warnings as failures. This is mutually exclusive with
-non_strict, the latter which is the default.
Added in version 3.4.2.
-non_strict
Skip source datasets that have issues with warnings, and
continue processing. This is the default.
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, input filenames are 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
C API
This utility is also callable from C with GDALBuildVRT().
AUTHOR
Even Rouault <even.rouault@spatialys.com>
COPYRIGHT
1998-2026
March 20, 2026 GDALBUILDVRT(1)