GDAL_MERGE(1)

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

✨ GDAL_MERGE ✨

okay bestie, welcome to your new fave utility 🫶 this one lives in the GDAL manual (that's the GDAL collection, section 1), and it's called gdal_merge. Let's get into it 💅

🌈 NAME 🌈

gdal_merge — mosaics a set of images. yes literally it just squishes a whole pile of rasters into one. iconic behavior 💖

🎀 SYNOPSIS 🎀

gdal_merge [--help] [--help-general]
              [-o <out_filename>] [-of <out_format>] [-co <NAME>=<VALUE>]...
              [-ps <pixelsize_x> <pixelsize_y>] [-tap] [-separate] [-q] [-v] [-pct]
              [-ul_lr <ulx> <uly> <lrx> <lry>] [-init "<value>[ <value>]..."]
              [-n <nodata_value>] [-a_nodata <output_nodata_value>]
              [-ot <datatype>] [-createonly] <input_file> [<input_file>]...

💜 DESCRIPTION 💜

So here's the tea: this utility will automatically mosaic a set of images. Obsessed. All the images must be in the same coordinate system and have a matching number of bands, but they may be overlapping, and at different resolutions. That's the flexible part, we love her. ✨

In areas of overlap, the last image will be copied over earlier ones. so order matters, bestie, don't come for me when the wrong tile is on top 🙈

Nodata/transparency values are considered on a band by band level, i.e. a nodata/transparent pixel on one source band will not set a nodata/transparent value on all bands for the target pixel in the resulting raster, nor will it overwrite a valid pixel value. she's precise like that 💅

NOTE: gdal_merge is a Python utility, and is only available if GDAL Python bindings are available. no bindings, no merge, that's the rule 😭
TIP: Equivalent in new "gdal" command line interface: See gdal raster mosaic.

okay now the options, bestie, there are a lot, hydrate first 🍓

  • --help — Show this help message and exit. cute and simple 💖
  • --help-general — Gives you a brief usage message for the generic GDAL commandline options, then exits. all the general-vibe stuff, none of the specifics ✨
  • -o out_filename — The name of the output file. It gets created if it doesn't already exist. defaults to "out.tif" — yes, fr fr, it just defaults to out.tif, no cap 👑
  • -of format — Select the output format. If you don't specify it, the format is guessed from the extension. Use the short format name, bestie, not the long dramatic one 🎀
  • -co NAME=VALUE — Many formats have one or more optional creation options that can be used to control particulars about the file created. For instance, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled. 🧚

The creation options available vary by format driver, and some simple formats have no creation options at all. A list of options supported for a format can be listed with the --format command line option, but the documentation for the format is the definitive source of information on driver creation options. See Raster drivers format specific documentation for legal creation options for each format. (legal as in allowed, not as in lawyers, okay? 💀)

  • -ot type — Force the output image bands to have a specific data type supported by the driver, which may be one of the following: Byte, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float32, Float64, CInt16, CInt32, CFloat32 or CFloat64. pick your girl 🌸
  • -ps pixelsize_x pixelsize_y — Pixel size to be used for the output file. If not specified, the resolution of the first input file will be used. so like, the first one is the main character, apparently 👑
  • -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. math girlies rise 🧮✨
  • -ul_lr ulx uly lrx lry — The extents of the output file. If not specified, the aggregate extents of all input files will be used. everybody gets a vote 🫶
  • -q, -quiet — Suppress progress messages. for when you want the silence, we respect it 🤫
  • -v — Generate verbose output of mosaicing operations as they are done. for when you want the play-by-play commentary, also valid 💬🔥
  • -separate — Place each input file into a separate band. stacking era 💅
  • -pct — Grab a pseudo-color table from the first input image, and use it for the output. Merging pseudo-colored images this way assumes that all input files use the same color table. ⚠️ so if they don't all share one, that's on you bestie ⚠️
  • -n nodata_value — Ignore pixels from files being merged in with this pixel value. bye bye pixels 🚫
  • -a_nodata output_nodata_value — Assign a specified nodata value to output bands. naming your own void 🌌
  • -init <"value(s)"> — Pre-initialize the output image bands with these values. However, it is not marked as the nodata value in the output file. So like, it's a starting value, not a declared empty — important distinction, iykyk. If only one value is given, the same value is used in all the bands. 🎀
  • -createonly — The output file is created (and potentially pre-initialized) but no input image data is copied into it. empty vessel energy, on purpose 🫙✨

⭐ RETURN STATUS CODE ⭐

The program returns status code 0 in case of success, and non-zero in case of error. (non-blocking errors emitted as warnings are considered as a successful execution, so like, don't panic over a little warning babe 💖)

🦋 EXAMPLES 🦋

🌸 Example 1: Creating an image with the pixels in all bands initialized to 255

gdal_merge -init 255 -o out.tif in1.tif in2.tif

every band starts at 255. simple. clean. slay. ✨

🌸 Example 2: Creating an RGB image that shows blue in pixels with no data

gdal_merge -init "0 0 255" -o out.tif in1.tif in2.tif

The first two bands will be initialized to 0 and the third band will be initialized to 255. so like, 0, 0, then blue. RGB girlies get it 💙

🌸 Example 3: Passing a large list of files to gdal_merge

ls -1 *.tif > tiff_list.txt

A large list of files can be passed to gdal_merge by listing them in a text file using the command above on Linux, or:

dir /b /s *.tif > tiff_list.txt

on Windows. The text file can then be passed to gdal_merge using --optfile:

gdal_merge -o mosaic.tif --optfile tiff_list.txt

no more 400 filenames on one line, we love a text file era 🫶📝

🌸 Example 4: Creating an RGB image by merging 3 different greyscale bands

Conduct "merging by stacking" with the -separate flag. Given three greyscale files that cover the same area, you can run:

gdal_merge -separate 1.tif 2.tif 3.tif -o rgb.tif

This maps 1.tif to red, 2.tif to green and 3.tif to blue. 🌈 three little files become one colorful icon, I'm emotional 😭

🌸 Example 5: Specifying overlap precedence

The last image in the input line comes out on top of the finished image stack. You might also need to use -n to note which value should not be copied into the destination image if it is not already defined as nodata.

gdal_merge -o merge.tif -n 0 image1.tif image2.tif image3.tif image4.tif

here image4.tif is the main character and everyone else is background 💅👑

👑 AUTHOR 👑

Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@intevation.de>

legends, honestly. thank you for your service 🫡💖

1998-2026

and that's the whole page bestie!! this was GDAL_MERGE(1) from the GDAL manual, dated Aug 18, 2026, and you absolutely ate reading all of it 🔥💖 go merge something gorgeous ✨🦋

📦 where this page comes from