GDAL_CALC(1) GDAL GDAL_CALC(1)
gdal_calc - Command line raster calculator with numpy syntax.
gdal_calc [--help] [--help-general]
--calc=expression --outfile=<out_filename> [-A <filename>]
[--A_band=<n>] [-B...-Z <filename>] [<other_options>]
DESCRIPTION
Command line raster calculator with numpy syntax. Use any basic
arithmetic supported by numpy arrays such as +, -, *, and / along
with logical operators such as >. Note that all files must have the
same dimensions (unless the --extent option is used), but no
projection checking is performed (unless the --projectionCheck option
is used).
NOTE:
gdal_calc 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 calc.
--help Show this help message and exit
--help-general
Gives a brief usage message for the generic GDAL commandline
options and exit.
--calc=<expression>
Calculation in numpy syntax using +, -, /, *, or any numpy
array functions (i.e. log10()). Multiple --calc options can
be listed to produce a multiband file (GDAL >= 3.2). See
Example 10.
-A <filename>
Input GDAL raster file, you can use any letter (a-z, A-Z).
(lower case supported since GDAL 3.3)
A letter may be repeated, or several values (separated by
space) can be provided (GDAL >= 3.3). The effect will be to
create a 3D numpy array. Since GDAL 3.5, wildcard exceptions
(using ?, *) are supported for all shells/platforms. In such
a case, the calculation formula must use this input as a 3D
array and must return a 2D array (see Example 3). If the
calculation does not return a 2D array an error will be
generated.
--A_band=<n>
Number of raster band for file A (default 1).
--outfile=<filename>
Output file to generate or fill.
--NoDataValue=<value>
Output NoDataValue (default datatype specific value). To
indicate not setting a NoDataValue use --NoDataValue=none
(GDAL >= 3.3)
NOTE:
Using the Python API: None value will indicate default
datatype specific value. 'none' value will indicate not
setting a NoDataValue.
--hideNoData
Added in version 3.3.
Ignores the input bands NoDataValue. By default, the input
bands NoDataValue are not participating in the calculation.
By setting this setting - no special treatment will be
performed on the input NoDataValue. and they will be
participating in the calculation as any other value. The
output will not have a set NoDataValue, unless you explicitly
specified a specific value by setting --NoDataValue=<value>.
--type=<datatype>
Output datatype, must be one of [Byte, Int8, UInt16, Int16,
UInt32, Int32, UInt64, Int64, Float64, Float32, CInt16,
CInt32, CFloat64, CFloat32].
NOTE:
Despite the datatype set using --type, when doing
intermediate arithmetic operations using operands of the
same type, the operation result will honor the original
datatype. This may lead into unexpected results in the
final result.
NOTE:
UInt64, Int64, CInt16, CInt32, CFloat32, CFloat64 have been
added in GDAL 3.5.3 Int8 has been added in GDAL 3.7
--format=<gdal_format>
GDAL format for output file.
--color-table=<filename>
Allows specifying a filename of a color table (or a ColorTable
object) (with Palette Index interpretation) to be used for the
output raster. Supported formats: txt (i.e. like gdaldem, but
color names are not supported), qlr, qml (i.e. exported from
QGIS)
--extent=<option>
Added in version 3.3.
This option determines how to handle rasters with different
extents. This option is mutually exclusive with the projwin
option, which is used for providing a custom extent.
For all the options below the pixel size (resolution) and SRS
(Spatial Reference System) of all the input rasters must be
the same.
ignore (default) - only the dimensions of the rasters are
compared. if the dimensions do not agree the operation will
fail.
fail - the dimensions and the extent (bounds) of the rasters
must agree, otherwise the operation will fail.
union - the extent (bounds) of the output will be the minimal
rectangle that contains all the input extents.
intersect - the extent (bounds) of the output will be the
maximal rectangle that is contained in all the input extents.
--projwin <ulx> <uly> <lrx> <lry>
Added in version 3.3.
This option provides a custom extent for the output, it is
mutually exclusive with the extent option.
--projectionCheck
Added in version 3.3.
By default, no projection checking will be performed. By
setting this option, if the projection is not the same for all
bands then the operation will fail.
--creation-option=<option>
Passes a creation option to the output format driver.
Multiple options may be listed. See format specific
documentation for legal creation options for each format.
--co=<option>
The same as creation-option.
--allBands=[a-z, A-Z]
Apply the expression to all bands of a given raster. When
--allBands is used, --calc may be specified only once. See
Example 11 and Example 12.
--overwrite
Overwrite output file if it already exists. Overwriting must
be understood here as deleting and recreating the file from
scratch. Note that if this option is not specified and the
output file already exists, it will be updated in place.
--debug
Print debugging information.
--quiet
Suppress progress messages.
Added in version 3.3.
The following options are available by using the Python interface of
gdal_calc. They are not available using the command prompt.
user_namespace
A dictionary of custom functions or other names to be
available for use in the Calc expression.
return_ds
If enabled, the output dataset will be returned from the
function and not closed.
color_table
Allows specifying a ColorTable object (with Palette Index
interpretation) to be used for the output raster.
Example 1: Average of two files
gdal_calc -A input1.tif -B input2.tif --outfile=result.tif --calc="(A+B)/2"
CAUTION:
If A and B inputs both have integer data types, integer division
will be performed. To avoid this, you can convert of one of the
operands to a floating point type before the division operation.
gdal_calc -A input.tif -B input2.tif --outfile=result.tif --calc="(A.astype(numpy.float64) + B) / 2"
Example 2: Summing three files
gdal_calc -A input1.tif -B input2.tif -C input3.tif --outfile=result.tif --calc="A+B+C"
Example 3: Combining three files into a 3D array and summing
gdal_calc -A input1.tif -A input2.tif -A input3.tif --outfile=result.tif --calc="numpy.sum(A,axis=0)".
Example 4: Average of three files
gdal_calc -A input1.tif -B input2.tif -C input3.tif --outfile=result.tif --calc="(A+B+C)/3"
Example 5: Average of three files, using 3D array
gdal_calc -A input1.tif input2.tif input3.tif --outfile=result.tif --calc="numpy.average(a,axis=0)".
Example 6: Maximum of three files
gdal_calc -A input1.tif -B input2.tif -C input3.tif --outfile=result.tif --calc="numpy.max((A,B,C),axis=0)"
Example 7: Maximum of three files, using a 3D array
gdal_calc -A input1.tif input2.tif input3.tif --outfile=result.tif --calc="numpy.max(A,axis=0)"
Example 8: Setting values of zero and below to NODATA
gdal_calc -A input.tif --outfile=result.tif --calc="A*(A>0)" --NoDataValue=0
Example 9: Using logical operator to keep a range of values from input
gdal_calc -A input.tif --outfile=result.tif --calc="A*logical_and(A>100,A<150)"
Example 10: Performing two calculations and storing results in separate
bands
gdal_calc -A input.tif --A_band=1 -B input.tif --B_band=2 \
--outfile=result.tif --calc="(A+B)/2" --calc="B*logical_and(A>100,A<150)"
Example 11: Add a raster to each band in a 3-band raster
gdal_calc -A 3band.tif -B 1band.tif --outfile result.tif --calc "A+B" --allBands A
The result will have three bands, where each band contains the values
of 1band.tif added to the corresponding band in 3band.tif.
Example 12: Add two three-band rasters
gdal_calc -A 3band_a.tif -B 3band_b.tif --outfile result.tif --calc "A+B" --allBands A --allBands B
The result will have three bands, where each band contains the values
of the corresponding band of 3band_a.tif added to the corresponding
band of 3band_b.tif.
Chris Yesson <chris dot yesson at ioz dot ac dot uk>, Etienne
Tourigny <etourigny dot dev at gmail dot com>
1998-2026
March 20, 2026 GDAL_CALC(1)
NAME
gdal_calc - Command line raster calculator with numpy syntax.
SYNOPSIS
gdal_calc [--help] [--help-general]
--calc=expression --outfile=<out_filename> [-A <filename>]
[--A_band=<n>] [-B...-Z <filename>] [<other_options>]
DESCRIPTION
Command line raster calculator with numpy syntax. Use any basic
arithmetic supported by numpy arrays such as +, -, *, and / along
with logical operators such as >. Note that all files must have the
same dimensions (unless the --extent option is used), but no
projection checking is performed (unless the --projectionCheck option
is used).
NOTE:
gdal_calc 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 calc.
--help Show this help message and exit
--help-general
Gives a brief usage message for the generic GDAL commandline
options and exit.
--calc=<expression>
Calculation in numpy syntax using +, -, /, *, or any numpy
array functions (i.e. log10()). Multiple --calc options can
be listed to produce a multiband file (GDAL >= 3.2). See
Example 10.
-A <filename>
Input GDAL raster file, you can use any letter (a-z, A-Z).
(lower case supported since GDAL 3.3)
A letter may be repeated, or several values (separated by
space) can be provided (GDAL >= 3.3). The effect will be to
create a 3D numpy array. Since GDAL 3.5, wildcard exceptions
(using ?, *) are supported for all shells/platforms. In such
a case, the calculation formula must use this input as a 3D
array and must return a 2D array (see Example 3). If the
calculation does not return a 2D array an error will be
generated.
--A_band=<n>
Number of raster band for file A (default 1).
--outfile=<filename>
Output file to generate or fill.
--NoDataValue=<value>
Output NoDataValue (default datatype specific value). To
indicate not setting a NoDataValue use --NoDataValue=none
(GDAL >= 3.3)
NOTE:
Using the Python API: None value will indicate default
datatype specific value. 'none' value will indicate not
setting a NoDataValue.
--hideNoData
Added in version 3.3.
Ignores the input bands NoDataValue. By default, the input
bands NoDataValue are not participating in the calculation.
By setting this setting - no special treatment will be
performed on the input NoDataValue. and they will be
participating in the calculation as any other value. The
output will not have a set NoDataValue, unless you explicitly
specified a specific value by setting --NoDataValue=<value>.
--type=<datatype>
Output datatype, must be one of [Byte, Int8, UInt16, Int16,
UInt32, Int32, UInt64, Int64, Float64, Float32, CInt16,
CInt32, CFloat64, CFloat32].
NOTE:
Despite the datatype set using --type, when doing
intermediate arithmetic operations using operands of the
same type, the operation result will honor the original
datatype. This may lead into unexpected results in the
final result.
NOTE:
UInt64, Int64, CInt16, CInt32, CFloat32, CFloat64 have been
added in GDAL 3.5.3 Int8 has been added in GDAL 3.7
--format=<gdal_format>
GDAL format for output file.
--color-table=<filename>
Allows specifying a filename of a color table (or a ColorTable
object) (with Palette Index interpretation) to be used for the
output raster. Supported formats: txt (i.e. like gdaldem, but
color names are not supported), qlr, qml (i.e. exported from
QGIS)
--extent=<option>
Added in version 3.3.
This option determines how to handle rasters with different
extents. This option is mutually exclusive with the projwin
option, which is used for providing a custom extent.
For all the options below the pixel size (resolution) and SRS
(Spatial Reference System) of all the input rasters must be
the same.
ignore (default) - only the dimensions of the rasters are
compared. if the dimensions do not agree the operation will
fail.
fail - the dimensions and the extent (bounds) of the rasters
must agree, otherwise the operation will fail.
union - the extent (bounds) of the output will be the minimal
rectangle that contains all the input extents.
intersect - the extent (bounds) of the output will be the
maximal rectangle that is contained in all the input extents.
--projwin <ulx> <uly> <lrx> <lry>
Added in version 3.3.
This option provides a custom extent for the output, it is
mutually exclusive with the extent option.
--projectionCheck
Added in version 3.3.
By default, no projection checking will be performed. By
setting this option, if the projection is not the same for all
bands then the operation will fail.
--creation-option=<option>
Passes a creation option to the output format driver.
Multiple options may be listed. See format specific
documentation for legal creation options for each format.
--co=<option>
The same as creation-option.
--allBands=[a-z, A-Z]
Apply the expression to all bands of a given raster. When
--allBands is used, --calc may be specified only once. See
Example 11 and Example 12.
--overwrite
Overwrite output file if it already exists. Overwriting must
be understood here as deleting and recreating the file from
scratch. Note that if this option is not specified and the
output file already exists, it will be updated in place.
--debug
Print debugging information.
--quiet
Suppress progress messages.
PYTHON OPTIONS
Added in version 3.3.
The following options are available by using the Python interface of
gdal_calc. They are not available using the command prompt.
user_namespace
A dictionary of custom functions or other names to be
available for use in the Calc expression.
return_ds
If enabled, the output dataset will be returned from the
function and not closed.
color_table
Allows specifying a ColorTable object (with Palette Index
interpretation) to be used for the output raster.
EXAMPLES
Example 1: Average of two files
gdal_calc -A input1.tif -B input2.tif --outfile=result.tif --calc="(A+B)/2"
CAUTION:
If A and B inputs both have integer data types, integer division
will be performed. To avoid this, you can convert of one of the
operands to a floating point type before the division operation.
gdal_calc -A input.tif -B input2.tif --outfile=result.tif --calc="(A.astype(numpy.float64) + B) / 2"
Example 2: Summing three files
gdal_calc -A input1.tif -B input2.tif -C input3.tif --outfile=result.tif --calc="A+B+C"
Example 3: Combining three files into a 3D array and summing
gdal_calc -A input1.tif -A input2.tif -A input3.tif --outfile=result.tif --calc="numpy.sum(A,axis=0)".
Example 4: Average of three files
gdal_calc -A input1.tif -B input2.tif -C input3.tif --outfile=result.tif --calc="(A+B+C)/3"
Example 5: Average of three files, using 3D array
gdal_calc -A input1.tif input2.tif input3.tif --outfile=result.tif --calc="numpy.average(a,axis=0)".
Example 6: Maximum of three files
gdal_calc -A input1.tif -B input2.tif -C input3.tif --outfile=result.tif --calc="numpy.max((A,B,C),axis=0)"
Example 7: Maximum of three files, using a 3D array
gdal_calc -A input1.tif input2.tif input3.tif --outfile=result.tif --calc="numpy.max(A,axis=0)"
Example 8: Setting values of zero and below to NODATA
gdal_calc -A input.tif --outfile=result.tif --calc="A*(A>0)" --NoDataValue=0
Example 9: Using logical operator to keep a range of values from input
gdal_calc -A input.tif --outfile=result.tif --calc="A*logical_and(A>100,A<150)"
Example 10: Performing two calculations and storing results in separate
bands
gdal_calc -A input.tif --A_band=1 -B input.tif --B_band=2 \
--outfile=result.tif --calc="(A+B)/2" --calc="B*logical_and(A>100,A<150)"
Example 11: Add a raster to each band in a 3-band raster
gdal_calc -A 3band.tif -B 1band.tif --outfile result.tif --calc "A+B" --allBands A
The result will have three bands, where each band contains the values
of 1band.tif added to the corresponding band in 3band.tif.
Example 12: Add two three-band rasters
gdal_calc -A 3band_a.tif -B 3band_b.tif --outfile result.tif --calc "A+B" --allBands A --allBands B
The result will have three bands, where each band contains the values
of the corresponding band of 3band_a.tif added to the corresponding
band of 3band_b.tif.
AUTHOR
Chris Yesson <chris dot yesson at ioz dot ac dot uk>, Etienne
Tourigny <etourigny dot dev at gmail dot com>
COPYRIGHT
1998-2026
March 20, 2026 GDAL_CALC(1)