GDAL_PROXIMITY(1)

💖 NAME 💖

gdal_proximity — bestie, it produces a raster proximity map. That's the whole job. 🌈

(it lives in section 1 of the GDAL manual, and honestly? iconic of it.)

---

🎀 SYNOPSIS 🎀

okay so here's the shape of the thing, copy it exactly, no cap:

gdal_proximity [--help] [--help-general]
                  <srcfile> <dstfile> [-srcband <n>] [-dstband <n>]
                  [-of <format>] [-co <name>=<value>]...
                  [-ot Byte/UInt16/UInt32/Float32/etc]
                  [-values <n>,<n>,<n>] [-distunits {PIXEL|GEO}]
                  [-maxdist <n>] [-nodata <n>] [-use_input_nodata {YES|NO}]
                  [-fixed-buf-val <n>]

---

✨ DESCRIPTION ✨

So gdal_proximity generates a raster proximity map that shows the distance from the center of each pixel to the center of the nearest pixel identified as a target pixel. And what counts as a target pixel? Pixels in the source raster whose value lands inside the set of target pixel values. Slay. 💅

NOTE: gdal_proximity is a Python utility, and is only available if GDAL Python bindings are available. So like... no bindings, no proximity map. Periodt. 😭

TIP: Equivalent in the new "gdal" command line interface: See gdal raster proximity.

---

🦋 the options, one by one, we're not skipping a single one 🦋

• --help — shows this help message and exits. bye bestie 👋
• --help-general — gives you a brief usage message for the generic GDAL commandline options and exits.
• <srcfile> — the source raster file, the one we use to identify target pixels. 👑
• <dstfile> — the destination raster file where the proximity map gets written. It may be a pre-existing file of the same size as srcfile. If it does not exist, it will be created. ✨
• -srcband <n> — which band in the source file to use (default is 1).
• -dstband <n> — which band in the destination file to use (default is 1).
• -of <format> — select the output format. If you don't specify it, the format is guessed from the extension. Use the short format name. 🫶
• -co <NAME>=<VALUE> — many formats have one or more optional creation options that can control particulars about the file being created. Like, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled. 💀

The creation options available vary by format driver, and some simple formats have no creation options at all. A list of options supported for a format can be listed with the --format command line option, but the documentation for the format is the definitive source of information on driver creation options. See Raster drivers format specific documentation for legal creation options for each format. (iykyk 📚)

• -ot <type> — specify a data type supported by the driver, which may be one of the following: Byte, UInt16, Int16, UInt32, Int32, Float32 (default), or Float64. Note that Float32 is the default — that's the main character here. ⭐
• -values <n>,<n>,<n> — a list of target pixel values in the source image to be considered target pixels. If not specified, all non-zero pixels will be considered target pixels.
• -distunits {PIXEL|GEO} — indicate whether distances generated should be in pixel or georeferenced coordinates (default PIXEL).
• -maxdist <n> — the maximum distance to be generated. The nodata value will be used for pixels beyond this distance. If a nodata value is not provided, the output band will be queried for its nodata value. If the output band does not have a nodata value, then the value 65535 will be used. Distance is interpreted in pixels unless -distunits GEO is specified. 👀
• -nodata <n> — specify a nodata value to use for the destination proximity raster.
• -use_input_nodata {YES|NO} — indicate whether nodata pixels in the input raster should be nodata in the output raster (default NO).
• -fixed-buf-val <n> — specify a value to be applied to all pixels that are within the -maxdist of target pixels (including the target pixels) instead of a distance value. 🔥

---

🌟 RETURN STATUS CODE 🌟

The program returns status code 0 in case of success, and non-zero in case of error. Note: non-blocking errors emitted as warnings are considered as a successful execution. So like, don't panic if you see a warning, the exit code is still fine. 😌

---

👑 AUTHOR 👑

Frank Warmerdam <warmerdam@pobox.com>

---

🎀 COPYRIGHT 🎀

1998-2026

---

okay that's the whole page bestie, you ate it up fr fr 🫶💖✨

source: GDAL  ·  dated: Aug 18, 2026 — GDAL_PROXIMITY(1), signing off, mwah 💋🌸