GDAL-VECTOR-UPDATE(1)

📦 version 3.13.3, in alpine 3.24, arch rolling, ubuntu stonking

💖 GDAL-VECTOR-UPDATE 💖

okay bestie, welcome to GDAL-VECTOR-UPDATE(1) — she's part of the GDAL squad and she is so good at what she does: she updates an existing vector dataset using an input vector dataset. 🦋

✨ Added in version 3.13. ✨ brand new, freshly dropped, we love to see it.

🌸 SYNOPSIS 🌸

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

Update an existing vector dataset with an input vector dataset.

Positional arguments:
  -i, --input <INPUT>                              Input vector datasets [required] [not available in pipelines]
  -o, --output <OUTPUT>                            Output vector dataset [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:
  --input-layer <INPUT-LAYER>                      Input layer name
  --output-layer <OUTPUT-LAYER>                    Output layer name
  --mode <MODE>                                    Set update mode. MODE=merge|update-only|append-only (default: merge)
  --key <KEY>                                      Field(s) used as a key to identify features [may be repeated]

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]

✨ DESCRIPTION ✨

gdal vector update is your girl for updating the features of an existing output vector dataset with the features of the input vector. 💅 She figures out which features match between input and output by looking at their feature ID by default — or, when you pass --key, by looking at the value of one or several columns that form a key. iykyk. 🔑

With the default merge mode, features that show up in both layers get updated, and features that only exist in the input layer get created over in the output layer. best of both worlds, honestly. 🫶

Now, the schemas of the input and output layers do not need to be identical (except on the columns you specify with --key) — but bestie, they really should use the same CRS for geometry columns, because no on-the-fly reprojection is done. none. zero. don't ask. 🙈 If a column exists in the input layer but not in the output layer, it will not be created. And if a column exists in the output layer and not in the input layer, its content will not be updated. the way that it just leaves things alone... iconic boundary-setting tbh.

You can also run gdal vector update as one step of a pipeline, where the input dataset is the output of the previous step. teamwork makes the dream work. 🌈

👑 PROGRAM-SPECIFIC OPTIONS 👑

  • --input-layer <INPUT-LAYER> — names the input layer. Must be specified if the input dataset has several layers, because she's not about to guess which one you meant. 💀
  • --key <KEY> — the field(s) used as a key to identify features. Got multiple fields? Specify --key multiple times, once per field. no cap. 🔥
  • --mode merge|update-only|append-only — defines how the updates go down. Default is merge.
    • merge (the default): features found in both layers get updated, and features only existing in the input layer get created in the output layer. ✨
    • update-only: features found in both layers get updated, and features only found in the input layer are ignored. she said "not today." 🙅
    • append-only: features found in both layers are not updated, and features only found in the input layer get created in the output layer. purely additive, main character energy. 💖
  • --output-layer <OUTPUT-LAYER> — names the output layer. Must be specified if the output dataset has several layers. same rule, same vibe. 🎀

⭐ STANDARD OPTIONS ⭐

  • --if, --input-format <format> — the format/driver name to be attempted when opening the input file(s). Lowkey you generally don't need to set this, but it's there for when automatic driver detection fails to pick the right driver and you need to skip it. You can repeat this option several times to list several candidate drivers. ⚠️ But note: it does not force those drivers to open the dataset. In particular, some drivers have requirements on file extensions. so pick wisely bestie.
    • May be repeated. 🔁
  • --oo, --open-option <NAME>=<VALUE> — dataset open option (format specific). 🧚
    • May be repeated. 🔁
  • --output-open-option, --output-oo <NAME>=<VALUE> — dataset open option for the output dataset (format specific).
    • ✨ Added in version 3.12. ✨
    • May be repeated. 🔁

💀 RETURN STATUS CODE 💀

She returns status code 0 when it's a success, and non-zero when there's an error. oh and — non-blocking errors that get emitted as warnings still count as a successful execution. so if you see a warning, breathe. it's fine. 😭

🌸 EXAMPLES 🌸

🎀 Example 1: Update existing out.gpkg with content of in.gpkg, using identifier as the key.

$ gdal vector update --key identifier in.gpkg out.gpkg

look at her go. ate that. 💅

💜 AUTHOR 💜

Even Rouault <even.rouault@spatialys.com> — legendary, we stan. 👑

1998-2026

and that's the whole page bestie, no notes. 🫶 this lil manual page came from the GDAL crew and landed on Aug 18, 2026 — go update something iconic with it. periodt. 💖✨🦋

📦 where this page comes from