GDAL-VECTOR-BUFFER(1)

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

🎀 GDAL-VECTOR-BUFFER 🎀

okay so this is the GDAL-VECTOR-BUFFER(1) page, aka the gdal-vector-buffer utility, and it is lowkey iconic 💖

💅 NAME 💅

gdal-vector-buffer — compute a buffer around geometries of a vector dataset 🦋

Added in version 3.12. ✨

🌸 SYNOPSIS 🌸

Usage: gdal vector buffer [OPTIONS] <INPUT> <OUTPUT> <DISTANCE>

Compute a buffer around geometries of a vector dataset.

Positional arguments:
  -i, --input <INPUT>                                  Input vector datasets [required] [not available in pipelines]
  -o, --output <OUTPUT>                                Output vector dataset [required] [not available in pipelines]
  --distance <DISTANCE>                                Distance to which to extend the geometry. [required]

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:
  -l, --layer, --input-layer <INPUT-LAYER>             Input layer name(s) [may be repeated] [not available in pipelines]
  -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]
  --lco, --layer-creation-option <KEY>=<VALUE>         Layer creation option [may be repeated] [not available in pipelines]
  --overwrite                                          Whether overwriting existing output dataset is allowed [not available in pipelines]
  --update                                             Whether to open existing dataset in update mode [not available in pipelines]
  --overwrite-layer                                    Whether overwriting existing output layer is allowed [not available in pipelines]
  --append                                             Whether appending to existing layer is allowed [not available in pipelines]
                                                       Mutually exclusive with --upsert
  --output-layer <OUTPUT-LAYER>                        Output layer name [not available in pipelines]
  --skip-errors                                        Skip errors when writing features [not available in pipelines]
  --active-layer <ACTIVE-LAYER>                        Set active layer (if not specified, all)
  --active-geometry <ACTIVE-GEOMETRY>                  Geometry field name to which to restrict the processing (if not specified, all)
  --endcap-style <ENDCAP-STYLE>                        Endcap style.. ENDCAP-STYLE=round|flat|square (default: round)
  --join-style <JOIN-STYLE>                            Join style.. JOIN-STYLE=round|mitre|bevel (default: round)
  --mitre-limit <MITRE-LIMIT>                          Mitre ratio limit (only affects mitered join style). (default: 5)
  --quadrant-segments <QUADRANT-SEGMENTS>              Number of line segments used to approximate a quarter circle. (default: 8)
  --side <SIDE>                                        Sets whether the computed buffer should be single-sided or not.. SIDE=both|left|right (default: both)

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]
  --output-oo, --output-open-option <KEY>=<VALUE>      Output open options [may be repeated] [not available in pipelines]
  --upsert                                             Upsert features (implies 'append') [not available in pipelines]
                                                       Mutually exclusive with --append

💜 DESCRIPTION 💜

so, gdal vector buffer computes a POLYGON or MULTIPOLYGON that represents all the points whose distance from a geometry/geography is less than or equal to a given distance. that's the whole vibe, bestie 🌈

a negative distance shrinks the geometry instead of expanding it, bestie. and a negative distance can shrink a polygon completely, in which case you just get POLYGON EMPTY back. for points and lines, negative distances always return empty results 😭

want pictures? see the PostGIS ST_Buffer docs for additional graphical illustrations of the effect of the different parameters. ✨

the output dataset is always written as MULTIPOLYGON, even when the input contains only simple POLYGON geometries. no cap. and lowkey note that negative buffer distances may also produce MULTIPOLYGON results. 🔥

using a buffer distance of 0 can sometimes repair invalid geometries, but the recommended approach is to use gdal vector make-valid for reliable geometry validation and repair. periodt. 💅

this command can also be used as a step of gdal vector pipeline. 🫶

🦋 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 vector dataset using the GDALG: GDAL Streamed Algorithm driver, and apply the specified pipeline in a on-the-fly / streamed way. it's giving main character energy ngl 🧚

NOTE: this command requires a GDAL build against the GEOS library. no GEOS, no buffering, iykyk 💀

👑 PROGRAM-SPECIFIC OPTIONS 👑

  • --distance <DISTANCE> — radius of the buffer around the input geometry. the unit of the distance is in georeferenced units of the source layer. 📏
  • --endcap-style round|flat|square — specifies the end cap style of the generated buffer. default is round. 🎀
    • [image] Buffered lines with endcap-style=round, endcap-style=flat and endcap-style=square.UNINDENT
  • --join-style round|mitre|bevel — sets the join style for outside (reflex) corners between line segments. default is round. 🌸
    • [image] Buffered lines with join-style=round, join-style=mitre and join-style=bevel.UNINDENT
  • --input-layer <NAME> — specifies one or more layer names to read and process. by default, all layers will be read and processed. and bestie, if you want to read and write all layers but only process a subset? use --active-layer. 🫶
  • --mitre-limit <MITRE-LIMIT> — sets the limit on the mitre ratio used for very sharp corners. this option only applies when join-style=mitre is used.

default is 5. 🔥

  • [image] Lines with a distance=2 buffer, and mitre-limit=5 on the left, and mitre-limit=1 on the right.UNINDENT

the mitre ratio is the ratio of the distance from the corner to the end of the mitred offset corner. when two line segments meet at a sharp angle, a miter join will extend far beyond the original geometry. (and in the extreme case will be infinitely far.) to prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. corners with a ratio which exceed the limit will be beveled. 💅

  • --output-layer <NAME> — name of the layer to which output should be written. if not specified, the output layer will have the same name as the input layer. cute and convenient ✨
  • --quadrant-segments <QUADRANT-SEGMENTS> — sets the number of line segments used to approximate an angle fillet in round joins. 🌈

this determines the maximum error in the approximation to the true buffer curve. the default value of 8 gives less than 2% max error in the buffer distance. for a max error of < 1%, use QS = 12. for a max error of < 0.1%, use QS = 18. the error is always less than the buffer distance (in other words, the computed buffer curve is always inside the true curve). ngl that's so satisfying 😌

  • [image] Buffered points with quadrant-segments=4 and quadrant-segments=20.UNINDENT
  • --side both|left|right — sets whether the computed buffer should be single-sided or on both sides (default). 🦋

left indicates that the buffer is generated on the left-hand side of the line, and right indicates that the buffer is generated on the right-hand side of the line, determined by the order of the line's vertices (i.e., the direction in which the line is drawn).

single-side buffering is only applicable to LINESTRING geometry and does not affect POINT or POLYGON geometries, and the end cap style is forced to square. periodt 💅

  • [image] Buffered lines with side=both, side=left and side=right.UNINDENT

✨ STANDARD OPTIONS ✨

okay bestie these are the options that basically every gdal vector subcommand shares, so learning them once = unlocked forever 💅

  • --append — says whether we're allowed to append features onto existing layer(s). Bonus: it also creates the output dataset for you if it doesn't exist yet. 🫶
  • --active-layer <ACTIVE-LAYER> — sets the active layer. When you name one, only the layer with that name gets processed — every other layer stays untouched, no notes 🙈. If you don't set this, literally all layers get processed.
  • --active-geometry <ACTIVE-GEOMETRY> — sets the active geometry field, picked by its name. Name one and only that geometry field gets processed; the other geometry fields are left alone. Skip it and all geometry fields are fair game. This one plays nicely together with --active-layer. 🌸
  • --co, --creation-option <NAME>=<VALUE> — so lots of formats have optional dataset creation options that control the little particulars of the file being created. Example: the GeoPackage driver has creation options that control the version. 🎀

May be repeated. 🔁

Which creation options exist depends entirely on the format driver, and some simple formats have literally zero creation options. You can list what a format supports with the --formats command line option, but fr fr the format's documentation is the definitive source for driver creation options. Go see the Vector drivers format specific documentation for the legal creation options of each format.

heads up: dataset creation options are not the same thing as layer creation options. don't mix them up bestie 😭
  • --if, --input-format <format> — the format/driver name you want it to attempt to open the input file(s) with. Usually you don't even need this, but it's there for when automatic driver detection fails to pick the right driver and you wanna skip it entirely. You can repeat this several times to list several candidate drivers. ⭐
note that it does not force those drivers to open the dataset. and some drivers have requirements on file extensions, so it's giving "suggestion, not a command" energy.

May be repeated. 🔁

  • --lco, --layer-creation-option <NAME>=<VALUE> — many formats have optional layer creation options controlling the particulars of the layer being created. Example: the GeoPackage driver has layer creation options to control the feature identifier or the geometry column name, setting the identifier or description, etc. ✨

May be repeated. 🔁

Which layer creation options exist varies by format driver, and some simple formats have none at all. --formats lists what a format supports, but the format documentation is the definitive source for driver creation options. See the Vector drivers format specific documentation for the legal creation options of each format.

and yes: layer creation options are different from dataset creation options. two different girlies, two different jobs 💅
  • --oo, --open-option <NAME>=<VALUE> — a dataset open option (format specific). 🌈

May be repeated. 🔁

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output vector format you want. You can get the allowed values with:
gdal --formats | grep vector | grep rw | sort
  • --output-open-option, --output-oo <NAME>=<VALUE> — added in version 3.12. It's a dataset open option for the output dataset (format specific). 👑

May be repeated. 🔁

  • --overwrite — lets the program overwrite an existing target file or dataset. Without it, by default gdal just errors out if the target file or dataset already exists. 💀
  • --overwrite-layer — whether overwriting the existing output vector layer is allowed. 🦋
  • --skip-errors — added in version 3.12. Whether failures to write feature(s) should be ignored. 🫶
real talk though: this option sets the size of the transaction unit to one feature at a time, which may cause severe slowdown when inserting into databases. iconic but at what cost 😭
  • --update — whether to open an existing output dataset in update mode. 🔥
  • --upsert — added in version 3.12. A variant of --append where the OGRLayer::UpsertFeature() operation is used to insert or update features instead of appending with OGRLayer::CreateFeature(). 🌟

This is currently implemented only in a few drivers: GPKG — GeoPackage vector, Elasticsearch: Geographically Encoded Objects for Elasticsearch, and MongoDBv3 (drivers that implement upsert expose the GDAL_DCAP_UPSERT capability).

The upsert operation uses the FID of the input feature, when it is set (and the FID column name is not the empty string), as the key to update existing features. It is crucial to make sure that the FID in the source and target layers are consistent. ⚠️

For the GPKG driver, it's also possible to upsert features whose FID is unset or non-significant (the --unset-fid option of gdal vector edit can be used to ignore the FID from the source feature), when there is a UNIQUE column that is not the integer primary key. 🧚

🌈 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 don't panic bestie 💜)

💖 EXAMPLES

Example 1: Compute a buffer of one km around input geometries (assuming the CRS is in meters)

$ gdal vector buffer --distance=1000 in.gpkg out.gpkg --overwrite

Example 2: Buffer a point dataset with 20 segments per quadrant (instead of default 8) to better approximate a circle

$ gdal vector buffer --distance=20 --quadrant-segments=20 points.gpkg point_buffers.gpkg

Example 3: Buffer lines to the left using join and end cap styles

$ gdal vector buffer --distance=10 --endcap-style=flat --side=left --join-style=mitre --mitre-limit=2 lines.gpkg lines-buffer-endcap.gpkg

Example 4: Clip and buffer a zipped line dataset as part of a pipeline

Bash 🐚

gdal vector pipeline \
! read "/vsizip/lines.zip" \
! clip --bbox 647903,6863599,648703,6864399 \
! buffer --distance=5 \
! write line-buffer.gpkg --overwrite

PowerShell 💙

gdal vector pipeline `
! read "/vsizip/lines.zip" `
! clip --bbox 647903,6863599,648703,6864399 `
! buffer --distance=5 `
! write line-buffer.gpkg --overwrite

👑 AUTHOR

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's the whole page bestie, you ate 💅 this one's from the GDAL crew, documented in the page dated Aug 18, 2026, and the manpage title is GDAL-VECTOR-BUFFER(1) — go buffer something gorgeous, ily 🦋✨

📦 where this page comes from