GDAL-VECTOR-CLIP(1)

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

💖 NAME 💖

gdal-vector-clip — clip a vector dataset, bestie. ✂️✨

Not me showing up fresh in version 3.11 — she's new here and already iconic, fr fr.

🦋 SYNOPSIS 🦋

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

That's the whole vibe: you hand her an <INPUT>, you hand her an <OUTPUT>, you sprinkle some [OPTIONS] on top, and she goes ✂️.

🎀 Positional arguments

  • -i, --input <INPUT> — the input vector datasets, aka the thing getting snipped. [required] and [not available in pipelines] — so if you're in a pipeline, this one's not for you.
  • -o, --output <OUTPUT> — the output vector dataset, aka where the clipped glow-up lands. Also [required] and [not available in pipelines].

💅 Common Options

  • -h, --help — show the help message and dip. no cap, sometimes that's all you need.
  • --json-usage — dump the usage as a JSON document and exit. for the girls who script everything 🫶
  • --config <KEY>=<VALUE> — a configuration option. [may be repeated] — stack 'em up.
  • -q, --quiet — quiet mode: no progress bar, no warning messages, just vibes. [not available in pipelines]

✨ Options

  • -l, --layer, --input-layer <INPUT-LAYER> — name(s) of the input layer. [may be repeated] [not available in pipelines]
  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — the output format. and yes, "GDALG" is 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 an existing output dataset is allowed. [not available in pipelines]
  • --update — whether to open the existing dataset in update mode. [not available in pipelines]
  • --overwrite-layer — whether overwriting an existing output layer is allowed. [not available in pipelines]
  • --append — whether appending to an existing layer is allowed. [not available in pipelines] Mutually exclusive with --upsert — pick a lane bestie 🚫
  • --output-layer <OUTPUT-LAYER> — the output layer name. [not available in pipelines]
  • --skip-errors — skip errors when writing features. [not available in pipelines]
  • --active-layer <ACTIVE-LAYER> — set the active layer (if not specified, all of them get the treatment).
  • --bbox <BBOX> — the clipping bounding box as xmin,ymin,xmax,ymax. Mutually exclusive with --geometry, --like
  • --bbox-crs <BBOX-CRS> — the CRS of the clipping bounding box.
  • --geometry <GEOMETRY> — the clipping geometry (WKT or GeoJSON). Mutually exclusive with --bbox, --like
  • --geometry-crs <GEOMETRY-CRS> — the CRS of the clipping geometry.
  • --like <DATASET> — a dataset to use as a template for bounds. Mutually exclusive with --bbox, --geometry
  • --like-sql <SELECT-STATEMENT> — a SELECT statement to run on the like dataset. Mutually exclusive with --like-where
  • --like-layer <LAYER-NAME> — the name of a layer of the like dataset.
  • --like-where <WHERE-EXPRESSION> — a WHERE SQL clause to run on the like dataset. Mutually exclusive with --like-sql

🔥 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 (which implies append). [not available in pipelines] Mutually exclusive with --append — again, pick ONE 🫠

🌸 DESCRIPTION 🌸

Okay so gdal vector clip clips a vector dataset using georeferenced coordinates. That's the whole job description and she eats every time.

You must specify one of --bbox, --geometry or --like. Like, that's not optional, that's the vibe check of this tool.

clip can also be used as a step of gdal vector pipeline. main character energy that works in ensemble casts too 💅

Now here's the part everyone skips and then gets confused about, so pay attention bestie 👀 — clipping sometimes results in geometries that are of a type not compatible with the geometry type. What she does about it:

  • For layers that are of a single geometry type (such as point, linestring, polygon), she splits multi-geometries or geometry collections into their parts, and only keeps the parts that are of that type.
  • She also promotes single geometry types (e.g. polygons) to multi geometry types (e.g. multi-polygons).
  • If the user needs to preserve any type of intersection, the layer must use the wkbUnknown (any geometry) type.
So basically: if you want zero geometry erasure, set your layer to wkbUnknown. no cap, that's the tea ☕

🎀 PROGRAM-SPECIFIC OPTIONS 🎀

✂️ --bbox <xmin>,<ymin>,<xmax>,<ymax>

The bounds you want to clip the dataset to, bestie. They're assumed to be in the CRS of the input dataset, unless --bbox-crs is specified.

The X and Y axis are the "GIS friendly ones" — meaning X is longitude or easting, and Y is latitude or northing. iykyk.

Mutually exclusive with --like and --geometry.

🌈 --bbox-crs <CRS>

The CRS in which the <xmin>, <ymin>, <xmax>, <ymax> values of --bbox are expressed. If you don't specify it, it's assumed to be the CRS of the input dataset.

Heads up though — specifying --bbox-crs does not involve doing vector reprojection. Instead, the bounds get reprojected from the bbox-crs to the CRS of the input dataset. Different thing, okay? don't conflate them 🙈

🦋 --geometry <WKT_or_GeoJSON>

A geometry, as a WKT or GeoJSON string, to clip the dataset to. Let's break it down:

  • If the input geometry is GeoJSON, its CRS is assumed to be WGS84, unless there's a CRS defined in the GeoJSON geometry or --geometry-crs is specified.
  • If the input geometry is WKT, its CRS is assumed to be the one of the input dataset, unless --geometry-crs is specified.
  • The X and Y axis are the "GIS friendly ones" again — X is longitude or easting, and Y is latitude or northing.

Mutually exclusive with --bbox and --like.

💜 --geometry-crs <CRS>

The CRS in which the coordinate values of --geometry are expressed. If not specified, it's assumed to be the CRS of the input dataset.

And again, for the people in the back — specifying --geometry-crs does not involve doing vector reprojection. The bounds are instead reprojected from the geometry-crs to the CRS of the input dataset. same deal as before, periodt.

🍓 --like <DATASET>

A vector or raster dataset to use as a template for bounds. Here's how she handles each:

  • If the dataset you specified is a raster, its rectangular bounds are used as the clipping geometry.
  • If the dataset you specified is a vector dataset, its polygonal geometries are unioned together to form the clipping geometry.
⚠️ beware that the result union might not be perfect if there are gaps between individual polygon features. not her fault, that's just geometry being geometry 😭

If several layers are present, --like-sql or --like-layer must be specified.

Mutually exclusive with --bbox and --geometry.

👑 --like-layer <LAYER-NAME>

Select the named layer from the vector clip dataset. Mutually exclusive with --like-sql — one or the other, queen.

💫 --like-sql <SELECT-STATEMENT>

Select the desired geometries from the vector clip dataset using an SQL query. Like, for real for real:

SELECT geom FROM my_layer WHERE country = 'France'

Mutually exclusive with --like-layer and --like-where.

🌸 --like-where <WHERE-EXPRESSION>

Restrict the desired geometries from the vector clip dataset layer based on an attribute query. For example:

country = 'France'

Mutually exclusive with --like-sql.

💖 STANDARD OPTIONS 💖

These are the options literally everywhere in gdal — not just this tool. So bestie, learn them once, flex forever. 🫶

  • --active-layer <ACTIVE-LAYER> — ok so this sets the active layer. When you name one, ONLY the layer with that name gets processed — every other layer is left completely untouched, no cap. And if you don't specify it at all? Then literally all layers are subject to the processing. 💅
  • --append — says whether we're allowed to append features onto existing layer(s). Highkey convenient, because it also creates the output dataset for you if it doesn't exist yet. ✨
  • --co, --creation-option <NAME>=<VALUE> — so many formats come with one or more optional dataset creation options that let you control little particulars about the file being created. Like, the GeoPackage driver supports creation options to control the version. Cute, right?

May be repeated. 🔁

The dataset creation options available vary by format driver, and some simple formats have no creation options at all (dry, I know). You can list which options a format supports with the --formats command line option — but the documentation for the format is the definitive source of information on driver creation options. See Vector drivers format specific documentation for the legal creation options for each format.

Not me reminding you: dataset creation options are different from layer creation options. Do not mix them up, I'm begging. 😭
  • --if, --input-format <format> — the format/driver name to be attempted when opening the input file(s). Generally you don't even need it — it's mostly there to skip automatic driver detection when that fails to pick the right driver. You can repeat this option several times to list several candidate drivers. Note that it does not force those drivers to open the dataset — some drivers have requirements on file extensions, so like, don't be shocked. 🙈

May be repeated. 🔁

  • --input-layer <INPUT-LAYER> — names one or more layers to process. By default, all layers get processed. But if you want to read and write all layers while only processing a subset? Use --active-layer. That's the whole vibe check. 🦋
  • --lco, --layer-creation-option <NAME>=<VALUE> — many formats have one or more optional layer creation options to control particulars about the layer being created. For instance, the GeoPackage driver supports layer creation options to control the feature identifier or geometry column name, setting the identifier or description, etc. Iconic. 👑

May be repeated. 🔁

Layer creation options available vary by format driver, and some simple formats have no layer 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 Vector drivers format specific documentation for legal creation options for each format.

And again, layer creation options are different from dataset creation options. Two separate situations, fr fr. 💀
  • --oo, --open-option <NAME>=<VALUE> — dataset open option (format specific).

May be repeated. 🔁

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output vector format to use. To get the allowed values, run:
gdal --formats | grep vector | grep rw | sort

slay. 🎀

  • --output-layer <NAME> — names the layer the features get written to. If you skip it, output layer names will just be the same as input layer names. Lowkey convenient. ✨
  • --output-open-option, --output-oo <NAME>=<VALUE> — Added in version 3.12.

Dataset open option for the output dataset (format specific).

May be repeated. 🔁

  • --overwrite — lets the program overwrite an existing target file or dataset. Otherwise, by default, gdal errors out if the target file or dataset already exists. So like, choose your fighter. 🔥
  • --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.

⚠️ Heads up bestie: this option sets the size of the transaction unit to one feature at a time, which may cause severe slowdown when inserting into databases. Severe. Slowdown. 💀
  • --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 is 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 as a successful execution — so like, a warning is not a fail, breathe. 😌)

🌸 EXAMPLES 🌸

✨ Example 1: Clip a GeoPackage file to the bounding box from longitude 2, latitude 49, to longitude 3, latitude 50 in WGS 84 ✨

$ gdal vector clip --bbox=2,49,3,50 --bbox-crs=EPSG:4326 in.gpkg out.gpkg --overwrite

periodt. 💅

👑 AUTHOR 👑

Even Rouault <even.rouault@spatialys.com>

1998-2026

okay bestie, that's the whole page 🫶 this was GDAL-VECTOR-CLIP(1), the source/version line is GDAL-VECTOR-CLIP(1) and the date on it is Aug 18, 2026 — go clip something iconic and stay hydrated 💖✨🌸

📦 where this page comes from