GDAL_POLYGONIZE(1)

💖 GDAL_POLYGONIZE(1) — the glow-up ✨

okay so bestie, welcome to the GDAL_POLYGONIZE(1) page 💅 this is the one that turns your raster into a whole polygon layer, and honestly? it eats.

---

🌸 NAME 🌸

gdal_polygonize — produces a polygon feature layer from a raster. that's it, that's the whole job, and she does it flawlessly 🫶

---

✨ SYNOPSIS ✨

gdal_polygonize [--help] [--help-general]
                   [-8] [-o <name>=<value>]... [-nomask]
                   [-mask <filename>] <raster_file> [-b <band>]
                   [-q] [-f <ogr_format>] [-lco <name>=<value>]...
                   [-overwrite] <out_file> [<layer>] [<fieldname>]

---

🦋 DESCRIPTION 🦋

so what she actually does: she makes vector polygons for every connected region of pixels in the raster that share a common pixel value 👑 and each of those polygons gets an attribute that tells you the pixel value of that polygon. so the polygons know where they came from. main character behaviour fr.

you can also hand her a raster mask, which decides which pixels are even eligible for processing (no mask, no entry 💅).

if the output vector datasource doesn't exist yet, she'll just create it. if it does already exist? she'll try to append to it. flexible queen.

she's built on top of the :GDALPolygonize() function, which is where the nitty-gritty details of the algorithm live if you're the type who reads the source (respect).

NOTE: gdal_polygonize is a Python utility, and is only available if GDAL Python bindings are available. no bindings, no polygoni— 😭

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

ok now the options, buckle up 🎀

• --help — shows you this help message and then dips. exit, stage left.
• --help-general — gives you a brief usage message for the generic GDAL commandline options and exits. the generic ones, not the specific ones, don't get it twisted.
• -8 — use 8 connectedness. the default is 4 connectedness. so like, do you want your pixels to know their diagonal neighbours too? yes? -8. iconic.
• -nomask — do not use the default validity mask for the input band (stuff like nodata, or alpha masks). girl said no mask today 🙈
• -mask <filename> — use the first band of the specified file as a validity mask (zero is invalid, non-zero is valid). if you don't specify one, the default validity mask for the input band (again: nodata, alpha masks, etc.) gets used — unless you passed -nomask, obviously.
• <raster_file> — the source raster file from which the polygons are derived. the raw material. the blueprint. the vibe check.
• -b <band> — the band on <raster_file> to build the polygons from. you can also set the value to "mask" to say "use the mask band of the first band", or "mask,band_number" for the mask of a specified band. very ✨choose your own adventure✨ of her.
• -f <ogr_format> — pick the output format. if you don't, the format gets guessed from the extension. use the short format name, bestie, not the long one.
• -o <NAME>=<VALUE> — Added in version 3.7. polygonize option. go read the :GDALPolygonize() documentation for the deets, iykyk.
• -lco <NAME>=<VALUE> — Added in version 3.7. layer creation option (format specific).
• -overwrite — Added in version 3.8. overwrite the output layer if it already exists. no hesitation, no mercy, periodt.
• <out_file> — the destination vector file to which the polygons will be written. the final home for your polygons 🏡
• <layer> — the name of the layer created to hold the polygon features.
• <fieldname> — the name of the field to create. defaults to "DN", in case you were wondering.
• -q — the script runs in quiet mode. the progress monitor is suppressed and routine messages are not displayed. silent. mysterious. lowkey terrifying but in a chic way 💀

---

🎀 RETURN STATUS CODE 🎀

she returns status code 0 when it's a success girlie, and non-zero when something went wrong. and heads up: non-blocking errors emitted as warnings are considered as a successful execution — so a lil warning noise does not a failure make 🫶

---

👑 AUTHOR 👑

Frank Warmerdam <warmerdam@pobox.com>

---

💜 COPYRIGHT 💜

1998-2026

---

and that's the whole page bestie!! go polygonize something gorgeous 🌈💖

xoxo, your GDAL_POLYGONIZE(1) page — GDAL, dated Aug 18, 2026, signing off ✨🦋💅