GDAL-RASTER-MOSAIC(1)

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

🌈 gdal-raster-mosaic — the GDAL manual, but make it cute 🎀

okay bestie, welcome to the gdal-raster-mosaic page from the GDAL manual (section 1, for the record ✨). grab a snack, we're building mosaics.

💖 NAME 💖

gdal-raster-mosaic — Build a mosaic.

Added in version 3.11.

✨ SYNOPSIS ✨

Usage: gdal raster mosaic [OPTIONS] <INPUTS>... <OUTPUT>

Build a mosaic, either virtual (VRT) or materialized.

so like, you give it a bunch of inputs and one output, and it cooks 🍓

🫶 Positional arguments

  • -i, --input <INPUTS> — Input raster datasets (or specify a @<filename> to point to a file containing filenames) [1.. values] [required] [not available in pipelines]
  • -o, --output <OUTPUT> — Output raster dataset [required] [not available in pipelines]

🌸 Common Options

  • -h, --help — Display help message and exit
  • --json-usage — Display usage as JSON document and exit
  • --config <KEY>=<VALUE> — Configuration option [may be repeated]
  • -q, --quiet — Quiet mode (no progress bar or warning message) [not available in pipelines]

💅 Options

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — Output format ("GDALG" allowed) [not available in pipelines]
  • --co, --creation-option <KEY>=<VALUE> — Creation option [may be repeated] [not available in pipelines]
  • --overwrite — Whether overwriting existing output dataset is allowed [not available in pipelines] — Mutually exclusive with --append
  • --append — Append as a subdataset to existing output [not available in pipelines] — Mutually exclusive with --overwrite
  • -b, --band <BAND> — Input band(s) (1-based index) [may be repeated]
  • --absolute-path — Whether the path to the input datasets should be stored as an absolute path
  • --resolution <xres>,<yres>|same|average|common|highest|lowest> — Target resolution (in destination CRS units) (default: same)
  • --bbox <BBOX> — Target bounding box as xmin,ymin,xmax,ymax (in destination CRS units)
  • --target-aligned-pixels — Round target extent to target resolution
  • --input-nodata <INPUT-NODATA> — Set nodata values for input bands. [1.. values]
  • --output-nodata <OUTPUT-NODATA> — Set nodata values at the destination band level. [1.. values]
  • --hide-nodata — Makes the destination band not report the NoData.
  • --add-alpha — Adds an alpha mask band to the destination when the source raster have none.
  • --pixel-function <PIXEL-FUNCTION> — Specify a pixel function to calculate output value from overlapping inputs. PIXEL-FUNCTION=area|argmax|argmin|cmul|complex|conj|dB|dB2amp|dB2pow|diff|div|exp|expression|geometric_mean|harmonic_mean|imag|intensity|interpolate_exp|interpolate_linear|inv|log10|max|mean|median|min|mod|mode|mul|norm_diff|phase|polar|pow|quantile|real|reclassify|replace_nodata|round|scale|sqrt|sum
  • --pixel-function-arg <NAME>=<VALUE> — Specify argument(s) to pass to the pixel function [may be repeated]

👑 Advanced Options

  • --if, --input-format <INPUT-FORMAT> — Input formats [may be repeated] [not available in pipelines]
  • --oo, --open-option <KEY>=<VALUE> — Open options [may be repeated] [not available in pipelines]

🦋 DESCRIPTION 🦋

This program builds a mosaic of a list of input GDAL datasets, that can be either a virtual mosaic in the VRT (Virtual Dataset) format, or in a more conventional raster format such as GeoTIFF. literally both vibes available, pick your fighter 💅

Wildcards '*', '?' or '['] of VSIGlob() can be used for input dataset names, even on files located on network file systems such as /vsis3/, /vsigs/, /vsiaz/, etc. Alternatively if a input dataset name is prefixed by the @ character, it will be assumed to contain the list of actual dataset names (one per line) to use as input datasets. so yes bestie you can just hand it a lil text file of paths and it'll figure it out, iconic 🎀

gdal raster mosaic does some checks to ensure that all files that will be put in the resulting file have similar characteristics: number of bands, projection, color interpretation, etc. If not, files that do not match the common characteristics will be skipped. it's giving group project where the matching ones get to stay ✨

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.

🚨 bestie, read that alpha part twice. alpha=0 on top does not get treated as "see-through" for compositing purposes here — it will override what's underneath. nodata does get respected, alpha does not (yet). that's the current behavior, not a bug report, ok?

Stating with GDAL 3.12, this command can also be used as the first step of gdal raster pipeline.

💜 GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET) 💜

This program supports serializing the command line as a JSON file using the GDALG output format. The resulting file can then be opened as a raster dataset using the GDALG: GDAL Streamed Algorithm driver, and apply the specified pipeline in a on-the-fly / streamed way. no materializing required, we're ✨streaming✨ 🦋

🌸 PROGRAM-SPECIFIC OPTIONS 🌸

--absolute-path

Added in version 3.12.0.

When writing a VRT file, 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). so like, if you're planning to move that VRT around, keep this in mind bestie 👑

--add-alpha

Adds an alpha mask band to the output 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. transparent where there's nothing, opaque where there's something — main character energy 🫶

-b, --band <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 output. Multiple -b switches may be used to select a set of input bands. repeat it as many times as your heart desires 💅

--bbox <xmin>,<ymin>,<xmax>,<ymax>

Set georeferenced extents of output file. The values must be expressed in georeferenced units. If not specified, the extent of the output is the minimum bounding box of the set of source rasters. Pixels within the extent of the output 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 --output-nodata or an alpha mask band is added with --add-alpha.

⚠️ okay so note the "value of zero" thing — those uncovered pixels are read as valid pixels worth zero, not as nodata, unless you say otherwise. plan accordingly 😭

--hide-nodata

Even if any band contains nodata value, giving this option makes the output band not report the NoData. Useful when you want to control the background color of the dataset. By using along with the --add-alpha option, you can prepare a dataset which doesn't report nodata value but is transparent in areas with no data. sneaky combo, lowkey genius 🌈

--input-nodata <value>[,<value>]...

Set nodata values for input bands (different values can be supplied for each band). 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.

--output-nodata <value>[,<value>]...

Set nodata values at the output 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 1). 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.

💀 do NOT forget the quotes when you pass multiple values, your shell will absolutely split them apart and it'll be a whole thing. quote it, bestie.

--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.

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.

--resolution {<xres,yres>|same|highest|lowest|average}

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.

  • same, the default, checks that all source rasters have the same resolution and errors out when this is not the case.
  • 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 will compute an average of pixel dimensions within the set of source rasters.
  • common determines the greatest common divisor of the source pixel dimensions, e.g. 0.2 for source pixel dimensions of 0.4 and 0.6.
  • <xres>,<yres>. The values must be expressed in georeferenced units. Both must be positive values.

--target-aligned-pixels

(target aligned pixels) align the coordinates of the extent of the output file to the values of the --resolution, such that the aligned extent includes the minimum extent. Alignment means that xmin / resx, ymin / resy, xmax / resx and ymax / resy are integer values.

to be continued, bestie — this page keeps going 🧚

✨ STANDARD OPTIONS ✨

okay bestie these are the shared besties that basically every gdal subcommand has, and gdal raster mosaic is no exception 💅 they apply to the whole program, not just to mosaic-ing:

  • --append — adds your input raster to an existing output file as a brand new subdataset 🫶 but listen, it only works with drivers that actually support stacking subdatasets, like GTiff (GeoTIFF File Format) and GPKG (GeoPackage raster). oh and bonus: if the output dataset doesn't exist yet, this will just create it for you. iconic.
  • --co, --creation-option <NAME>=<VALUE> — a lot of formats have optional creation options, and these let you control the little details of the file you're creating 🎀 think of the GeoTIFF driver, which has creation options for compression and for whether the file should be tiled. yes queen, you get to decide all of that.

May be repeated.

ngl the available creation options vary wildly by format driver, and some simple formats have literally zero creation options. you can get a list of what a format supports with the --formats command line option, but fr fr the documentation for the format is the definitive source for driver creation options. so go check the Raster drivers format specific documentation for the legal creation options of each format, k?

  • --if, --input-format <format> — the format/driver name that should be attempted when opening your input file(s) 👀 usually you don't need this at all, but it's a lifesaver when automatic driver detection fails to pick the right driver. you can repeat it several times to hand over several candidate drivers. that said, note that it doesn't force those drivers to open the dataset — some drivers are picky about file extensions, so no promises 💀

May be repeated.

  • --oo, --open-option <NAME>=<VALUE> — a dataset open option, format specific. yes it's giving very specific, and yes it's here for you.

May be repeated.

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output raster format you wanna use 🌈 allowed values may be given by:
gdal --formats | grep raster | grep rw | sort
  • --overwrite — lets the program overwrite an existing target file or dataset 💥 otherwise, by default, gdal just errors out if the target file or dataset already exists. she's protective like that.

🌟 RETURN STATUS CODE 🌟

the program returns status code 0 when everything slays ✨ and non-zero when there's an error. and heads up: non-blocking errors that get emitted as warnings are considered a successful execution, so don't panic if you see a little warning noise 🫶

🎀 EXAMPLES 🎀

💙 Example 1: Make a virtual mosaic with blue background colour (RGB: 0 0 255)

gdal raster mosaic --hide-nodata --output-nodata=0,0,255 doq/*.tif doq_index.vrt

🌸 Example 2: Create a Cloud Optimized GeoTIFF (COG) mosaic from all GeoTIFFs in a folder

because the size of the resulting GeoTIFF will be more than 4 GB, the BIGTIFF=YES creation option is used 🫡 big files need big moves.

gdal raster mosaic --output-format COG --creation-option BIGTIFF=YES *.tif mosaic.tif

👑 AUTHOR 👑

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's a wrap bestie 💖 this page came from the GDAL source docs, version info dated Aug 18, 2026, and yeah, it's GDAL-RASTER-MOSAIC(1) — go forth and mosaic, you absolute main character 🌈✨
📦 where this page comes from