GDAL_CALC(1)

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

✨ GDAL_CALC — your raster calculator, but make it numpy ✨

hiii bestie!! 💖 you just opened the GDAL manual (section 1, so it's <pink>GDAL_CALC(1)</pink> in the corner, iykyk). This is the whole entire tea on gdal_calc, no cap, nothing left out. Buckle up 🎀

🌸 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 💅

okay so it's a command line raster calculator with numpy syntax. ✨ You can use literally any basic arithmetic that numpy arrays support — like +, -, *, and / — plus logical operators such as >. Genuinely iconic.

Heads up though: all your files must have the same dimensions (unless you're using the --extent option, slay). But no projection checking is performed unless you pass --projectionCheck. So yeah, it will not vibe check your projections for you 🙈

📌 NOTE: gdal_calc is a Python utility, and it's only available if the GDAL Python bindings are available. No bindings, no calculator, periodt.
💡 TIP: Equivalent in new "gdal" command line interface: See gdal raster calc.

👑 OPTIONS 👑

  • --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. (twins 💕)
  • --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. ⚠️ (deleting and recreating from scratch is not a drill, bestie — read that twice.)
  • --debug — Print debugging information. 🐛
  • --quiet — Suppress progress messages. 🤫

🔥 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 zero = ate, non-zero = did not eat 💀

🐍 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. (sorry shell girlies 😔)

  • 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 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> — legends, honestly 🫶

1998-2026

and that's the whole page, bestie!! 🌈💜 this one shipped as part of GDAL, and the footer stamped it <pink>GDAL_CALC(1)</pink> dated Aug 18, 2026. go forth and calculate, you absolute icon 👑✨

📦 where this page comes from