GDAL-VECTOR-EDIT(1)

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

✨ NAME ✨

Bestie, welcome to GDAL-VECTOR-EDIT(1) — the manual page for gdal-vector-edit, which is here to Edit metadata of a vector dataset. 💅

Added in version 3.11. (yes, she's new-ish and she knows it 🎀)

🌈 SYNOPSIS 🌈

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

Edit metadata 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]

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
  --skip-errors                                        Skip errors when writing features [not available in pipelines]
  --active-layer <ACTIVE-LAYER>                        Set active layer (if not specified, all)
  --geometry-type <GEOMETRY-TYPE>                      Layer geometry type
  --crs <CRS>                                          Override CRS (without reprojection)
  --metadata <KEY>=<VALUE>                             Add/update dataset metadata item [may be repeated]
  --unset-metadata <KEY>                               Remove dataset metadata item [may be repeated]
  --layer-metadata <KEY>=<VALUE>                       Add/update layer metadata item [may be repeated]
  --unset-layer-metadata <KEY>                         Remove layer metadata item [may be repeated]
  --unset-fid                                          Unset the identifier of each feature and the FID column name

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 like, gdal vector edit</p> is your girl for editing metadata off a vector dataset: its CRS, the layer geometry type, and dataset and layer metadata. That's the whole job. Metadata glow-up only. ✨

She can also be used as a step of gdal vector pipeline. (yes she serves in pipelines too, main character energy fr fr 👑)

🫶 Features are not modified. Not the geometry, not the attributes. Just the metadata. Periodt.

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

Okay so this is lowkey the coolest part: 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 it will apply the specified pipeline in a on-the-fly / streamed way. No cap, it just vibes and streams. 💫

💖 PROGRAM-SPECIFIC OPTIONS 💖

Here come the options bestie, one by one, nothing skipped, we don't do skipping here 💅

  • --crs <CRS> — Override CRS, without reprojecting.

The coordinate reference systems that can be passed are anything supported by the OGRSpatialReference::SetFromUserInput() call. That includes:

  • EPSG Projected, Geographic or Compound CRS (i.e. EPSG:4296)
  • a well known text (WKT) CRS definition
  • PROJ.4 declarations
  • or the name of a .prj file containing a WKT CRS definition

null or none can be specified to unset an existing CRS. (bye CRS 👋)

  • --geometry-type <GEOMETRY-TYPE> — Change the layer geometry type to be one of:
    • GEOMETRY
    • POINT
    • LINESTRING
    • POLYGON
    • MULTIPOINT
    • MULTILINESTRING
    • MULTIPOLYGON
    • GEOMETRYCOLLECTION
    • CURVE
    • CIRCULARSTRING
    • COMPOUNDCURVE
    • SURFACE
    • CURVEPOLYGON
    • MULTICURVE
    • MULTISURFACE
    • POLYHEDRALSURFACE
    • or TIN

Z, M or ZM suffixes can be appended to the above values to indicate the dimensionality. 🌈

😭 Note that feature geometries themselves are not modified. So like, this option can be used to fix an inappropriate geometry type at the layer level. The whole vibe is layer-level, got it?
  • --layer-metadata <KEY>=<VALUE> — Add/update metadata item, at the layer level. 🎀
  • --metadata <KEY>=<VALUE> — Add/update metadata item, at the dataset level. 🎀
  • --unset-fid — Added in version 3.12.

Can be specified to prevent the name of the source FID column and source feature IDs from being reused for the target layer. This option can for example be useful if selecting source features with a ORDER BY clause. 🫶

  • --unset-metadata <KEY> — Remove metadata item, at the dataset level. 🗑️
  • --unset-layer-metadata <KEY> — Remove metadata item, at the layer level. 🗑️

✨ STANDARD OPTIONS ✨

These are the glow-up basics, bestie. Every gdal command speaks this language 💅

  • --active-layer <ACTIVE-LAYER> — sets the active layer. When you give it one, only that one layer (the one matching that name) gets processed; all the other layers stay untouched, like, completely unbothered. If you don't pass this at all, every layer gets processed. periodt.
  • --append — is it okay to append features onto layer(s) that already exist? That's the vibe check. Also, cute bonus: it creates the output dataset if it isn't there yet 🫶
  • --co, --creation-option <NAME>=<VALUE> — okay so lots of formats have one or more optional dataset creation options that let you control the little particulars of the file being created. Iconic example: the GeoPackage driver supports creation options that control the version ✨

May be repeated.

Which dataset creation options exist totally depends on the format driver, and some simple formats have literally none, zero, nada. You can list what a format supports with the --formats command line option, but bestie, the format's own documentation is the definitive source on driver creation options. See Vector drivers format specific documentation for the legal creation options for each format.

Heads up: dataset creation options are not the same thing as layer creation options. Don't mix them up 🙈
  • --if, --input-format <format> — format/driver name to attempt to open the input file(s) with. Normally you don't even need it, but it's your rescue plan when automatic driver detection fails to pick the right driver. You can repeat this option several times to line up several candidate drivers 🌈

Note that it does not force those drivers to open the dataset — it's a suggestion, not a demand. In particular, some drivers have requirements on file extensions, so it might still say no.

May be repeated.

  • --input-layer <INPUT-LAYER> — names one or more layers to process. By default every layer gets processed. If you want to read and write all the layers but only process a subset of them, use --active-layer instead. iykyk 💅
  • --lco, --layer-creation-option <NAME>=<VALUE> — many formats have one or more optional layer creation options for controlling the particulars of 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. 🎀

May be repeated.

Which layer creation options exist varies by format driver, and some simple formats have none at all. Again: you can list what a format supports with the --formats command line option, but the format documentation is the definitive source on driver creation options. See Vector drivers format specific documentation for the legal creation options for each format.

And again, because it matters: layer creation options are different from dataset creation options 🫠
  • --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 are we going with, bestie? The allowed values can be given by:
gdal --formats | grep vector | grep rw | sort
  • --output-layer <NAME> — the name of the layer the features get written into. If you don't specify it, the output layer names will just be the same as the input layer names. keeping it consistent, we love that 🌸
  • --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, be intentional about this one.
  • --overwrite-layer — is overwriting the existing output vector layer allowed or not? That's the question 💅
  • --skip-errors — Added in version 3.12.

Should failures to write feature(s) just be ignored? Note that this option sets the size of the transaction unit to one feature at a time, which may cause severe slowdown when inserting into databases 💀 (fr, it can be rough).

  • --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. Note that non-blocking errors emitted as warnings are considered a successful execution — they're just little warnings, not a crisis 🫶

🦋 EXAMPLES 🦋

Example 1: Change the CRS of a GeoPackage file (without reprojecting it) and its geometry type

$ gdal vector edit --crs=EPSG:4326 --geometry-type=POLYGONZM in.gpkg out.gpkg --overwrite

Example 2: Apply a CRS to a Shapefile

If a Shapefile is missing its associated .prj file, it can be created as follows:

$ gdal vector edit --crs=EPSG:3857 in.shp out.shp

💖 AUTHOR 💖

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's the whole page, bestie 🎀 thank you for reading the GDAL-VECTOR-EDIT(1) manual page, which came from GDAL and is dated Aug 18, 2026. go forth and edit those vectors, you're literally the main character 💅✨

📦 where this page comes from