GDAL_CALC(1)

📦
version 3.4.3 · 2 versions
, in epel 9

✨ GDAL_CALC(1) ✨ — the gdal_calc glow-up (GDAL manual, bestie edition)

okay so you opened the GDAL manual and landed on GDAL_CALC(1) — congrats, you're in the right place 💖 this is the page for gdal_calc, the command line raster calculator, and it's genuinely iconic. let's get into it.

🌸 NAME 🌸

gdal_calc — command line raster calculator with numpy syntax. that's the whole vibe. numpy brain, terminal body. 💅

🎀 SYNOPSIS 🎀

gdal_calc.py --calc=expression --outfile=out_filename [-A filename]
             [--A_band=n] [-B...-Z filename] [other_options]

🦋 DESCRIPTION 🦋

Command line raster calculator with numpy syntax, periodt. use any basic arithmetic supported by numpy arrays — like +, -, *, and \ — along with logical operators such as >. it's giving math but make it a CLI ✨

heads up bestie 👑: 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). so like… it will simply not notice if your projections don't match. you've been warned 🫶

🧚 the options, one by one

  • --help — show this help message and exit. classic.
  • -h — the same as --help. same energy, shorter name 💅
  • --calc=expression — the calculation itself, 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). yes bestie, multiband — stack 'em 😭🔥
  • -A <filename> — input gdal raster file, and you can use any letter (a-z, A-Z). (lower case supported since GDAL 3.3 🎉)

a letter may be repeated (GDAL >= 3.3). the effect will be to create a 3-dim numpy array. in such a case, the calculation formula must use this input as a 3-dim array and must return a 2D array (see examples below). in case the calculation does not return a 2D array, an error would be generated. so like, read that twice, it matters 💀

  • --A_band=<n> — number of raster band for file A (default 1).
  • --outfile=<filename> — output file to generate or fill. the whole point, honestly.
  • --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. yes they're different. no you cannot mix them up. i don't make the rules 😭
  • --hideNoData — new 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>. so it's a real "choose your fighter" situation 💅
  • --type=<datatype> — output datatype, must be one of [Int32, Int16, Float64, UInt16, Byte, UInt32, Float32].
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. not me finding this out the hard way — you don't have to, bestie 🫶
  • --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). aesthetic AND functional 🌈
  • --extent=<option> — new 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. the options:
    • 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> — new in version 3.3. this option provides a custom extent for the output, and it is mutually exclusive with the extent option. pick one, babe ✨
  • --projectionCheck — new 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. main character energy: it finally cares 👑
  • --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. short and slay.
  • --allBands=[a-z, A-Z] — process all bands of given raster (a-z, A-Z). requires a single calc for all bands. one calc to rule them all 🔥
  • --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. so like… very different outcomes, choose wisely 💀
  • --debug — print debugging information.
  • --quiet — suppress progress messages. for when you just want peace 🧘‍♀️

💜 PYTHON OPTIONS 💜

new in version 3.3. these are available by using the python interface of gdal_calc, and they are not available using the command prompt. iykyk 🐍

  • 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 would 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 ⭐

okay bestie, this is the part where it all clicks. watch 💖

add two files together

gdal_calc.py -A input1.tif -B input2.tif --outfile=result.tif --calc="A+B"

average of two layers

gdal_calc.py -A input1.tif -B input2.tif --outfile=result.tif --calc="(A+B)/2"
NOTE 🙈: in the previous example, beware that if A and B inputs are of the same datatype, for example integers, you may need to force the conversion of one of the operands before the division operation.
gdal_calc.py -A input.tif -B input2.tif --outfile=result.tif --calc="(A.astype(numpy.float64) + B) / 2"

add three files together (two options with the same result)

gdal_calc.py -A input1.tif -B input2.tif -C input3.tif --outfile=result.tif --calc="A+B+C"

new in version 3.3:

gdal_calc.py -A input1.tif -A input2.tif -A input3.tif --outfile=result.tif --calc="numpy.sum(A,axis=0)"

average of three layers (two options with the same result)

gdal_calc.py -A input1.tif -B input2.tif -C input3.tif --outfile=result.tif --calc="(A+B+C)/3"

new in version 3.3:

gdal_calc.py -A input1.tif -A input2.tif -A input3.tif --outfile=result.tif --calc="numpy.average(a,axis=0)"

maximum of three layers (two options with the same result)

gdal_calc.py -A input1.tif -B input2.tif -C input3.tif --outfile=result.tif --calc="numpy.max((A,B,C),axis=0)"

new in version 3.3:

gdal_calc.py -A input1.tif -A input2.tif -A input3.tif --outfile=result.tif --calc="numpy.max(A,axis=0)"

set values of zero and below to null

gdal_calc.py -A input.tif --outfile=result.tif --calc="A*(A>0)" --NoDataValue=0

using logical operator to keep a range of values from input

gdal_calc.py -A input.tif --outfile=result.tif --calc="A*logical_and(A>100,A<150)"

work with multiple bands

gdal_calc.py -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)"

🌈 AUTHOR 🌈

Chris Yesson <chris dot yesson at ioz dot ac dot uk>, Etienne Tourigny <etourigny dot dev at gmail dot com> — literal legends, we stan 🫶👑

1998-2026

and that's the page, bestie 🎀 official GDAL GDAL_CALC(1) manual, dated Jan 08, 2026, source/version GDAL. go forth and calculate — you're gonna eat 💅✨

📦 where this page comes from