GDAL-RASTER-NODATA-TO-ALPHA(1)

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

✨ NAME ✨

gdal-raster-nodata-to-alpha — swap out those icky nodata value(s) for a whole alpha band 💅

Oh and bestie, heads up: this one's Added in version 3.12. (yes it's new, yes it's fresh, periodt)

🎀 SYNOPSIS 🎀

Usage: gdal raster nodata-to-alpha [OPTIONS] <INPUT> <OUTPUT>

Replace nodata value(s) with an alpha band.

Positional arguments:
  -i, --input <INPUT>                                  Input raster datasets [required] [not available in pipelines]
  -o, --output <OUTPUT>                                Output raster dataset [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:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format ("GDALG" allowed) [not available in pipelines]
  --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated] [not available in pipelines]
  --overwrite                                          Whether overwriting existing output dataset is allowed [not available in pipelines]
                                                       Mutually exclusive with --append
  --append                                             Append as a subdataset to existing output [not available in pipelines]
                                                       Mutually exclusive with --overwrite
  --nodata <NODATA>                                    Override nodata value of input band(s) (numeric value, 'nan', 'inf', '-inf') [may be repeated]

Advanced Options:
  --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated] [not available in pipelines]
  --oo, --open-option <KEY>=<VALUE>                    Open options [may be repeated] [not available in pipelines]

🦋 DESCRIPTION 🦋

So <pink>gdal raster nodata-to-alpha</pink> is literally that girl: she rolls up, looks at the nodata value metadata chilling on the bands of your input dataset, and uses it to build you an alpha band. Iconic behaviour, no notes. 💖

What if your dataset is playing hard to get and has no explicit nodata value set? Not a problem, bestie — you can just hand one over yourself with the --nodata option.

And listen, the cutest part: if the input dataset has no nodata value and you never passed --nodata? This program is a no-op and it is safe to run anyway. It just vibes. Nothing happens. No drama. 🫶

🌈 GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET) 🌈

Okay so this is actually so cool. This program can serialize the whole command line as a JSON file using the GDALG output format. That file can then be opened as a raster dataset using the GDALG: GDAL Streamed Algorithm driver, and it'll apply the pipeline you specified in a full on-the-fly / streamed way. Streamed. On the fly. Main character energy fr fr. ✨

💅 PROGRAM-SPECIFIC OPTIONS 💅

  • --nodata <NODATA> — Override the nodata value of input band(s). It takes a numeric value, or 'nan', 'inf', '-inf'. You can either specify one value, or as many values as you have input bands — your call, choose your fighter. 👑 And here's the tea: when multiple values are specified, a pixel only counts as invalid if it matches the nodata values on all bands. Sneaky little AND logic, slay.

⭐ STANDARD OPTIONS ⭐

  • --co, --creation-option <NAME>=<VALUE> — Lots of formats have one or more optional creation options that control the particulars of the file being created. For example, the GeoTIFF driver has creation options for compression, and for whether the file should be tiled. So many little knobs, so little time. 🎛️

May be repeated. (say it again for the people in the back)

Which creation options exist depends entirely on the format driver, and ngl some of the simple formats have no creation options at all. You can list the options supported for a format with the --formats command line option, buuut the documentation for the format is the definitive source of truth on driver creation options. See Raster drivers format specific documentation for the legal creation options for each format. 👀

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — Which output raster format to use. Curious what's allowed? Run:
gdal --formats | grep raster | grep rw | sort
  • --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE> — Output data type, and your options are: Byte, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, CInt16, CInt32, Float32, Float64, CFloat32, CFloat64. Pick your fave, bestie. 🍓

💀 RETURN STATUS CODE 💀

The program returns status code 0 when it succeeds, and non-zero when there's an error. Quick clarification though, because this trips people up: non-blocking errors that get emitted as warnings still count as a successful execution. So a warning ≠ a fail. Noted. 😌

🔥 EXAMPLES 🔥

Example 1

$ gdal raster nodata-to-alpha input_with_nodata.tif output_with_alpha_band.tif

That's it. That's the whole flex. Input with nodata in, output with alpha band out. Go off. 💜

🌸 AUTHOR 🌸

Even Rouault <even.rouault@spatialys.com>

1998-2026

And that's the whole page, bestie — brought to you by the GDAL manual page collection, this one dated Aug 18, 2026. Go make some alpha bands, you absolute legend. 🎀✨

📦 where this page comes from