GDAL-RASTER-EDIT(1)

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

💖 GDAL-RASTER-EDIT(1) 💖

okay bestie, gather round, because this is gdal-raster-edit, straight out of the GDAL manual (section 1, the user-commands girlies). It edits a raster dataset in place — like, right on the file, no copy, no backup, no take-backs. 🫶

Added in version 3.11, so it's a newer icon but it's already main character energy.

✨ SYNOPSIS ✨

Usage: gdal raster edit [OPTIONS] <DATASET>

Edit a raster dataset.

Positional arguments:
  --dataset <DATASET>                                         Dataset (to be updated in-place, unless --auxiliary) [required] [not available in pipelines]

Common Options:
  -h, --help                                                  Display help message and exit
  --json-usage                                                Display usage as JSON document and exit
  --config <KEY>=<VALUE>                                      Configuration option [may be repeated]
  -q, --quiet                                                 Quiet mode (no progress bar or warning message) [not available in pipelines]

Options:
  --auxiliary                                                 Ask for an auxiliary .aux.xml file to be edited [not available in pipelines]
  -b, --band <BAND>                                           Active band (1-based index)
  --crs <CRS>                                                 Override CRS (without reprojection)
  --bbox <BBOX>                                               Bounding box as xmin,ymin,xmax,ymax
  --nodata <NODATA>                                           Assign a specified nodata value to output bands ('none', numeric value, 'nan', 'inf', '-inf')
  --color-interpretation <[all|<BAND>=]<COLOR-INTEPRETATION>  Set band color interpretation [may be repeated]
  --color-map <COLOR-MAP>                                     Color map filename
                                                              Mutually exclusive with --unset-color-table
  --scale <[<BAND>=]<SCALE>                                   Override band scale factor [may be repeated]
  --offset <[<BAND>=]<OFFSET>                                 Override band offset constant [may be repeated]
  --metadata <KEY>=<VALUE>                                    Add/update dataset metadata item [may be repeated]
  --unset-color-table                                         Unset color table on 1st band or the one specified with --band
                                                              Mutually exclusive with --color-map
  --unset-metadata <KEY>                                      Remove dataset metadata item(s) [may be repeated]
  --unset-metadata-domain <DOMAIN>                            Remove dataset metadata domain(s) [may be repeated]
  --gcp <GCP>                                                 Add ground control point, formatted as pixel,line,easting,northing[,elevation], or @filename [may be repeated]
  --stats                                                     Compute statistics, using all pixels
                                                              Mutually exclusive with --approx-stats
  --approx-stats                                              Compute statistics, using a subset of pixels
                                                              Mutually exclusive with --stats
  --hist                                                      Compute histogram

Advanced Options:
  --oo, --open-option <KEY>=<VALUE>                           Open options [may be repeated] [not available in pipelines]

🌸 DESCRIPTION 🌸

So like… gdal raster edit edits a raster dataset. That's the whole vibe. 💅

And the plot twist? This subcommand can also show up as a potential step inside gdal raster pipeline. Yes bestie, it's a crossover episode. 🔥

🎀 PROGRAM-SPECIFIC OPTIONS 🎀

  • --approx-stats — computes raster band statistics for all bands, but here's the tea: it may compute them based on overviews or just a subset of all the tiles. Which is so useful if you're in a hurry and don't need precise stats. Speed over precision, periodt. ⚡
NOTE: this option is not available when the command is part of a pipeline. 🙈
  • --auxiliary — forces the dataset open in read-only mode. And for drivers that implement the Persistent Auxiliary Metadata (PAM) mechanism, your changes get saved in an auxiliary side car file with the extension .aux.xml. Cute, contained, no drama on the main file. ✨
  • -b, --band <BAND> — added in version 3.13.

This is the index (starting at 1, bestie, we count like humans here) of the band that the following options apply to: --color-map, --unset-color-table. If you don't say anything, it defaults to one. 🎯

  • --bbox <xmin>,<ymin>,<xmax>,ymax — overrides the spatial bounding box, in CRS units, without reprojecting or subsetting. Like, it just says "this is the box now," it does NOT move any pixels. x is longitude values for a geographic CRS and easting for a projected CRS. y is latitude values for a geographic CRS and northing for a projected CRS. 🌍
  • --color-map <COLOR-MAP> — added in version 3.13.

A color map filename containing the association between various raster values and the corresponding wished color, set on the first band — or the one you specified with --band. And it can be either a GDAL dataset with a color table attached to its first band, or a text-based color configuration. Both are valid, no picking favorites. 🎨

The text-based color configuration file generally contains 4 columns per line: the raster value and the corresponding Red, Green, Blue component (between 0 and 255). The raster value must be an integer value between 0 and 65535. It can also be expressed as a percentage — 0% being the minimum value found in the raster, 100% the maximum value. She's flexible. 💁

An extra column can optionally be added for the alpha component. If it's not specified, full opacity (255) is assumed. ✨

Various field separators are accepted: comma, tabulation, spaces, ':'.

Common colors used by GRASS can also be specified by using their name, instead of the RGB triplet. The supported list is: white, black, red, green, blue, yellow, magenta, cyan, aqua, grey/gray, orange, brown, purple/violet and indigo. And yes, GMT .cpt palette files are also supported (COLOR_MODEL = RGB only). 🌈

Note: the syntax of the color configuration file is derived from the one supported by the GRASS r.colors utility. ESRI HDR color table files (.clr) also match that syntax. The alpha component, and the support of tab and comma as separators, are GDAL-specific extensions. 👑

For example:

3500   white
2500   235:220:175
50%   190 185 135
700    240 250 150
0      50  180  50
  • --crs <CRS> — overrides the CRS, without reprojecting. That's it, that's the deal. 💫

The coordinate reference systems that can be passed are anything supported by the OGRSpatialReference::SetFromUserInput() call — which includes EPSG Projected, Geographic or Compound CRS (i.e. EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 declarations, or the name of a .prj file containing a WKT CRS definition. So many doors, all open. 🚪

null or none can be specified to unset an existing CRS. Say goodbye. 👋

Note that the spatial extent is also left unchanged. Ngl, the extent does not care. 🙅

  • --dataset <DATASET> — dataset name, to be updated in-place, unless --auxiliary is set. Required. You literally cannot skip this one, bestie. 🚨
  • --gcp <GCP> — added in version 3.12.

Sets ground control point(s), replacing any existing GCPs (not me evicting the old ones 😭). Each GCP must be formatted as a string "pixel,line,easting,northing" or "pixel,line,easting,northing,elevation". Each GCP must be specified with a --gcp argument. 🧭

It's also possible to provide a single --gcp argument whose value is the filename of a vector dataset, prefixed with @. This dataset must have a single layer with the following required fields column, line, x, y, and optionally id, info and z. 📍

  • --hist — computes histogram information for all bands. 📊
NOTE: this option is not available when the command is part of a pipeline. 💀
  • --color-interpretation [all|<BAND>=]<COLOR-INTERPRETATION> — added in version 3.13.

Sets band color interpretation. May be repeated. 🔁

<COLOR-INTERPRETATION> is one of red, green, blue, alpha, gray, undefined, pan, coastal, rededge, nir, swir, mwir or lwir.

Several syntaxes are supported:

  • specifying all=<COLOR-INTERPRETATION>: set the color interpretation on all bands.
  • specifying as many <COLOR-INTERPRETATION> as there are bands, starting from band 1 to the last band.
  • specifying the color interpretation on a subset of bands with <BAND>=<COLOR-INTERPRETATION> where band is the band number starting at 1.
  • --scale [<BAND>=]<SCALE> — added in version 3.13.

Sets the band scale factor. May be repeated. 🔁

Several syntaxes are supported:

  • specifying one single <SCALE>: set the scale on all bands.
  • specifying as many <SCALE> as there are bands, starting from band 1 to the last band.
  • specifying the scale on a subset of bands with <BAND>=<SCALE> where band is the band number starting at 1.
  • --offset [<BAND>=]<OFFSET> — added in version 3.13.

Sets the band offset constant. May be repeated. 🔁

Several syntaxes are supported:

  • specifying one single <OFFSET>: set the offset on all bands.
  • specifying as many <OFFSET> as there are bands, starting from band 1 to the last band.
  • specifying the offset on a subset of bands with <BAND>=<OFFSET> where band is the band number starting at 1.
  • --metadata <KEY>=<VALUE> — add/update a metadata item, at the dataset level. May be repeated. 🏷️
  • --nodata <value> — overrides the nodata value. 🕳️

null or none can be specified to unset an existing nodata value. Poof. ✨

  • --stats — computes raster band statistics for all bands. 📈
  • --unset-color-table — added in version 3.13.

Removes the color table associated to the first band, or the one specified by --band. Bye bye color table, you were iconic. 💔

  • --unset-metadata <KEY> — removes a metadata item, at the dataset level. May be repeated. 🗑️
  • --unset-metadata-domain <DOMAIN> — added in version 3.12.

Removes a metadata domain, at the dataset level. May be repeated. 🧹

🌟 STANDARD OPTIONS 🌟

  • --oo, --open-option <NAME>=<VALUE> — dataset open option (format specific). 🛠️

May be repeated.

🏁 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 a warning is not a fail, bestie — it's just the program being honest with you. 😌

✨ EXAMPLES ✨

ok bestie these are the lil recipes, copy-paste energy, go off 💅

🎀 Example 1: Override (without reprojecting) the CRS of a dataset

$ gdal raster edit --crs=EPSG:32632 my.tif

🦋 Example 2: Override (without reprojecting or subsetting) the bounding box of a dataset

$ gdal raster edit --bbox=2,49,3,50 my.tif

🌸 Example 3: Add a metadata item

$ gdal raster edit --metadata AUTHOR=EvenR my.tif

⭐ Example 4: Remove a metadata item

$ gdal raster edit --unset-metadata AUTHOR my.tif

🫶 Example 5: Add 2 ground control point (GCP) for (column=0,line=0,X=2,Y=49) and (column=50,line=100,X=3,Y=48)

$ gdal raster edit --gcp 0,0,2,49 --gcp 50,100,3,48 my.tif

💖 Example 6: Add ground control point (GCP) from gcps.csv, that must have fields named column, line, x and y.

$ gdal raster edit --gcp @gcps.csv my.tif
psst, see that @? that's the "bestie I put it in a file" move. and no cap, that CSV must have fields named column, line, x and y or it's not gonna work 😭

🌈 Example 7: Set red, green, blue, NIR color interpretation to a 4-band dataset

$ gdal raster edit --color-interpretation red,green,blue,nir 4band.tif

👑 AUTHOR

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's the whole page bestie, we ate fr fr 🍓 the source/version on the tin is GDAL-RASTER-EDIT(1) and the date stamped on it is Aug 18, 2026 — go forth and edit those rasters, main character energy only ✨🧚💅

📦 where this page comes from