GDAL_MERGE(1) GDAL GDAL_MERGE(1)
gdal_merge - Mosaics a set of images.
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>]...
This utility will automatically mosaic a set of images. 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. In areas of overlap, the last image will be copied over
earlier ones. 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.
NOTE:
gdal_merge is a Python utility, and is only available if GDAL
Python bindings are available.
TIP:
Equivalent in new "gdal" command line interface:
See gdal raster mosaic.
--help Show this help message and exit
--help-general
Gives a brief usage message for the generic GDAL commandline
options and exit.
-o <out_filename>
The name of the output file, which will be created if it does
not already exist (defaults to "out.tif").
-of <format>
Select the output format. If not specified, the format is
guessed from the extension. Use the short format name.
-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.
-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.
-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.
-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.
-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.
-q, -quiet
Suppress progress messages.
-v Generate verbose output of mosaicing operations as they are
done.
-separate
Place each input file into a separate band.
-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.
-n <nodata_value>
Ignore pixels from files being merged in with this pixel
value.
-a_nodata <output_nodata_value>
Assign a specified nodata value to output bands.
-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. 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.
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
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.
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
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.
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
Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer
<silke@intevation.de>
1998-2026
March 20, 2026 GDAL_MERGE(1)
NAME
gdal_merge - Mosaics a set of images.
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
This utility will automatically mosaic a set of images. 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. In areas of overlap, the last image will be copied over
earlier ones. 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.
NOTE:
gdal_merge is a Python utility, and is only available if GDAL
Python bindings are available.
TIP:
Equivalent in new "gdal" command line interface:
See gdal raster mosaic.
--help Show this help message and exit
--help-general
Gives a brief usage message for the generic GDAL commandline
options and exit.
-o <out_filename>
The name of the output file, which will be created if it does
not already exist (defaults to "out.tif").
-of <format>
Select the output format. If not specified, the format is
guessed from the extension. Use the short format name.
-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.
-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.
-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.
-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.
-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.
-q, -quiet
Suppress progress messages.
-v Generate verbose output of mosaicing operations as they are
done.
-separate
Place each input file into a separate band.
-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.
-n <nodata_value>
Ignore pixels from files being merged in with this pixel
value.
-a_nodata <output_nodata_value>
Assign a specified nodata value to output bands.
-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. 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.
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
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.
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
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.
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
AUTHOR
Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer
<silke@intevation.de>
COPYRIGHT
1998-2026
March 20, 2026 GDAL_MERGE(1)