GDAL-VECTOR-RASTERIZE(1)

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

💖 GDAL-VECTOR-RASTERIZE(1) 💖

okay bestie, this is the GDAL-VECTOR-RASTERIZE(1) manual page, aka the glow-up guide for gdal-vector-rasterize. she burns vector geometries into a raster and she does it flawlessly. no gatekeeping here 💅✨

🌸 NAME 🌸

gdal-vector-rasterize — Burn vector geometries into a raster

Added in version 3.11. 🫶

✨ SYNOPSIS ✨

Usage: gdal vector rasterize [OPTIONS] <INPUT> <OUTPUT>

Burns vector geometries into a raster. periodt.

🎀 Positional arguments 🎀

  • -i, --input <INPUT> — input vector datasets [required]
  • -o, --output <OUTPUT> — output raster dataset [required]

💅 Common Options 💅

  • -h, --help — shows the help message and exits
  • --json-usage — shows usage as a JSON document and exits
  • --config <KEY>=<VALUE> — configuration option, repeatable [may be repeated]
  • -q, --quiet — quiet mode: no progress bar, no warning message. heads up: not available in pipelines [not available in pipelines]

🔥 Options 🔥

okay so these are the main-character options, bestie. every single one matters, don't skip 🫶:

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — sets the output format, pick your fave 💅
  • --co, --creation-option <KEY>=<VALUE> — creation option, and yeah you can stack it [may be repeated]
  • --overwrite — says whether overwriting an existing output dataset is allowed 👀
  • -b, --band <BAND> — the band(s) to burn values into, 1-based index, and it can repeat [may be repeated]
  • --invert — flips the rasterization, invert style
  • --all-touched — turns on the ALL_TOUCHED rasterization option
  • --burn <BURN> — the burn value, repeatable [may be repeated]
  • -a, --attribute-name <ATTRIBUTE-NAME> — the attribute name
  • --3d — says a burn value should be pulled from the feature's Z values
  • -l, --input-layer <INPUT-LAYER> — input layer name
    • Mutually exclusive with --sql
  • --where <WHERE> — SQL where clause
  • --sql <SQL> — SQL select statement
    • Mutually exclusive with --input-layer
  • --dialect <DIALECT> — SQL dialect
  • --nodata <NODATA> — assigns a specified nodata value to output bands
  • --init <INIT> — pre-initializes output bands with a specified value, repeatable [may be repeated]
  • --crs <CRS> — overrides the projection for the output file
  • --transformer-option <NAME>=<VALUE> — sets a transformer option suitable to pass to GDALCreateGenImgProjTransformer2, repeatable [may be repeated]
  • --extent <xmin>,<ymin>,<xmax>,<ymax> — sets the target georeferenced extent [4 values]
  • --resolution <xres>,<yres> — sets the target resolution [2 values]
    • Mutually exclusive with --size
  • --tap, --target-aligned-pixels — (target aligned pixels) aligns the coordinates of the extent of the output file to the values of the resolution
    • Depends on --resolution
  • --size <xsize>,<ysize> — sets the target size in pixels and lines [2 values]
    • Mutually exclusive with --resolution
  • --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE> — output data type. OUTPUT-DATA-TYPE=UInt8|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64
  • --optimization <OPTIMIZATION> — forces the algorithm used (results are identical). OPTIMIZATION=AUTO|RASTER|VECTOR (default: AUTO)
  • --add — adds to existing raster
  • --update — says whether to open existing dataset in update mode

🌈 Advanced Options 🌈

for the deep-cut besties 🧚:

  • --oo, --open-option <KEY>=<VALUE> — open options, repeatable [may be repeated]
  • --if, --input-format <INPUT-FORMAT> — input formats, repeatable [may be repeated]

🦋 DESCRIPTION 🦋

gdal vector rasterize burns vector geometries into a raster. that's the whole vibe, fr fr.

By default (unless --update or --add is specified), a new raster is created with a specified resolution (--resolution) or size (--size). Pixel values will either be set to a constant (the value 1, or some other value specified with --burn), the Z value of feature geometries (with --3d), or the value of a field specified with --attribute-name.

The left figure illustrates the default rasterization behavior, where only pixels on the line render path are included.

The right figure shows the effect of --all-touched, where every pixel that touches the input polygons is included.

Since GDAL 3.12, this algorithm can be part of a gdal pipeline.

The following options are available:

Added in version 3.12.

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

This program supports serializing the command line as a JSON file using the GDALG output format. The resulting file can then be opened as a raster dataset using the GDALG: GDAL Streamed Algorithm driver, and apply the specified pipeline in an on-the-fly / streamed way. iconic streaming behavior, no cap ✨

NOTE: However this algorithm is not natively streaming compatible. Consequently a temporary dataset will be generated, which may cause significant processing time at opening.

✨ PROGRAM-SPECIFIC OPTIONS ✨

okay bestie, this is where the actual magic happens 💅 these are the flags that only exist for gdal vector rasterize, and yes, you're gonna wanna know all of them.

  • --3d — says "hey, please pull the burn value out of the Z values of the feature" 🦋 it works with points and lines (and for lines it does linear interpolation along each segment). For polygons? only works properly if they're flat, as in every single vertex has the same Z value. no cap.
  • --add — instead of burning a fresh new value in, this adds the new value onto whatever's already in the raster. it implies --update btw. literally perfect for heatmaps, go off 🌈
  • --all-touched — turns on the ALL_TOUCHED rasterization option.
⚠️ NOTE, and listen closely: when this is enabled, the order of your input features (lines or polygons) can change the results. when two features touch each other, the last one (i.e. the topmost) decides the burned pixel value at that edge. if you want something more predictable, you may wish to use the --sql option to reorder the features with ORDER BY. iykyk 🙈
  • -a, --attribute-name <ATTRIBUTE-NAME> — the name of the attribute / field that the burn value gets retrieved from, per feature. GDAL will attempt to parse that field value as a number, and if that doesn't work out? a value of zero gets written instead. zero thoughts head empty energy 💀
  • --band, -b <BAND> — the band(s) to burn values into. may be repeated 🔥
  • --burn <BURN> — the burn value. may be repeated ✨
  • --crs <CRS> — overrides the projection for the output file. if you don't specify it, the projection of the input vector file gets used (if it's available). ⚠️ when you do use this option, there's no reprojection of features from the input vector's CRS to the specified CRS of the output raster — so only use this to correct an invalid source CRS, bestie, not to convert anything. the <CRS> can be any of the usual GDAL/OGR forms: complete WKT, PROJ.4, EPSG:n, or a file containing the WKT.
  • --extent <xmin>,<ymin>,<xmax>,<ymax> — sets georeferenced extents. the values must be in georeferenced units. skip it and the output file's extent becomes the extent of the vector layers 💫
  • --init <INIT> — pre-initialize output bands with a specified value. may be repeated 🎀
  • -l, --input-layer <INPUT-LAYER> — tells it which layer(s) from the datasource to use for input features. may be specified multiple times, but ⚠️ at least one layer name or a -sql option must be specified — not both.
  • --invert — inverts the rasterization. so it burns the fixed burn value (or the burn value associated with the first feature) into all the parts of the image that are not inside the provided polygon. like uno reverse but for pixels 🔄
⚠️ NOTE: when your vector features have a polygon nested inside another polygon (think an island in a lake), GDAL must be built against GEOS to get correct results. no GEOS, no correct island. periodt.
  • --nodata <NODATA> — assigns a specified nodata value to the output bands 🙈
  • --optimization <OPTIMIZATION> — forces which algorithm gets used (and dw, the results are identical either way, this is purely a performance thing). the raster mode is used in most cases and it optimises read/write operations. the vector mode is useful when you've got a decent amount of input features and it optimises CPU use — that mode has to be used with tiled images to actually be efficient. the auto mode (which is the default) chooses the algorithm based on input and output properties. she's smart like that 💅
  • --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE> — forces the output bands to be of the indicated data type. defaults to Float64, unless the attribute field you're burning is of type Int64 — in that case Int64 is used for the output raster data type if the output driver supports it 🧚
  • --resolution <xres>,<yres> — sets the target resolution. values must be in georeferenced units, and both must be positive. ⚠️ note that --resolution cannot be used with --size.
  • --size <xsize>,<ysize> — sets the output file size in pixels and lines. ⚠️ note that --size cannot be used with --resolution. and if one of the two values is set to 0, it'll be computed from the other value so the aspect ratio of the extent stays intact. clever girl 🎀
  • --sql <SQL>|@<filename> — an SQL statement to be evaluated against the datasource, producing a virtual layer of features to be burned in. the @filename syntax can be used to say "the content is in the file you're pointing at" 📂
  • --dialect <DIALECT> — SQL dialect 💬

by default the native SQL of an RDBMS is used when using gdal vector sql. if you're using sql as a step of a gdal vector pipeline, this is only true if the step preceding sql is read — otherwise the OGRSQL dialect is used.

if a datasource doesn't support SQL natively, the default is to use the OGRSQL dialect, which can also be specified with any data source.

the SQL SQLite dialect can be chosen with the SQLITE and INDIRECT_SQLITE dialect values, and this can be used with any data source. overriding the default dialect may be beneficial, since the capabilities of the SQL dialects vary.

supported dialects can be checked with gdal --format. for example:

$ gdal --format "PostgreSQL"
[...]
Supported SQL dialects: NATIVE OGRSQL SQLITE
[...]

$ gdal --format "ESRI Shapefile"
[...]
Supported SQL dialects: OGRSQL SQLITE
[...]
  • --tap, --target-aligned-pixels — (target aligned pixels) aligns the coordinates of the extent of the output file to the values of --resolution, such that the aligned extent includes the minimum extent. "alignment" here means that xmin / resx, ymin / resy, xmax / resx and ymax / resy are all integer values. ⚠️ --tap requires --resolution.
  • --transformer-option <NAME>=<VALUE> — sets a transformer option suitable for passing to GDALCreateGenImgProjTransformer2(). this gets used when converting geometry coordinates into target raster pixel space. for example you can use it to specify RPC-related transformer options 👑
  • --where <WHERE> — an optional SQL WHERE-style query expression, applied to select which features get burned in from the input layer(s) 🔍

🌟 STANDARD OPTIONS 🌟

these ones show up all over the GDAL CLI, so they're basically the group chat regulars 💖

  • --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 instance, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled.

may be repeated.

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 --formats command line option, but the documentation for the format is the definitive source of information on driver creation options. see the Raster drivers format specific documentation for the legal creation options for each format 📚

  • --if, --input-format <format> — format/driver name to be attempted when opening the input file(s). it's generally not necessary to specify it, but you can use it to skip automatic driver detection when that fails to select the appropriate driver. this option can be repeated several times to specify several candidate drivers. ⚠️ note that it does not force those drivers to open the dataset — in particular, some drivers have requirements on file extensions.

may be repeated.

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

may be repeated.

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output raster format to use. allowed values may be given by gdal --formats | grep raster | grep rw | sort.
  • --overwrite — allows the program to overwrite an existing target file or dataset. otherwise, by default, gdal errors out if the target file or dataset already exists 💀
  • --update — whether to open an existing output dataset in update mode.

🚦 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 a successful execution — so a lil warning never killed nobody 🫶).

💫 EXAMPLES 💫

Example 1: Burn a shapefile into a raster

the following would burn all polygons from mask.shp into the RGB TIFF file work.tif, in the color red (RGB = 255,0,0).

gdal vector rasterize -b 1,2,3 --burn 255,0,0 -l mask mask.shp work.tif

Example 2: The following would burn all "class A" buildings into the output elevation file, pulling the top elevation from the ROOF_H attribute. Burn a shapefile into a raster using a specific where condition to select features

okay this one's doing a lot in one line and honestly? slay.

gdal vector rasterize -a ROOF_H --where "class='A'" -l footprints footprints.shp city_dem.tif

Example 3: The following would burn all polygons from footprint.shp into a new 1000x1000 rgb TIFF as the color red.

📝 NOTE: - -b is not used here — the order of the --burn options determines the bands of the output raster. iconic behaviour.
gdal vector rasterize --burn 255,0,0 --ot Byte --size 1000,1000 -l footprints footprints.shp mask.tif

Example 4: Burn a shapefile into a raster using a specific where condition to select features, and restrict the extent to the one of selected features

pipeline girlies rise 🧚 this one pipes it all the way through:

gdal pipeline read /vsizip/vsicurl/https://www2.census.gov/geo/tiger/TIGER2025/STATE/tl_2025_us_state.zip ! \
                filter --where  "stusps = 'CA'" --update-extent ! \
                rasterize  --burn 1 --size 1500,1500 --datatype Byte ! \
                write out.png --overwrite

👑 AUTHOR 👑

Alessandro Pasotti <elpaso@itopen.it> — thank you for your service, legend 🫡

1998-2026

aaaand that's the whole page bestie, you made it to the end 🎉 this one's from the GDAL crew, GDAL-VECTOR-RASTERIZE(1), dated Aug 18, 2026 — so go forth, rasterize responsibly, and remember: layers or sql, never both 💅✨

📦 where this page comes from