GDAL-VECTOR-CONVERT(1)

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

🎀 NAME 🎀

gdal-vector-convert — the manual page (yep, she's the GDAL-VECTOR-CONVERT(1) one, hi bestie 💖) — converts a vector dataset.

Added in version 3.11. ✨

✨ SYNOPSIS ✨

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

Convert 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 [not available in pipelines]
  --skip-errors                                        Skip errors when writing features [not available in pipelines]
  --no-create-empty-layers                             Avoid creating layers to which no features will be written [not available in pipelines]

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 💅

gdal vector convert is literally here to convert data data between different formats. (Yes, the page says "data data" and honestly? iconic, no notes, we're keeping it fr fr. 😭)

Think of it as the glow-up station: data goes in one format, comes out another, looking expensive. 🦋

🔥 STANDARD OPTIONS 🔥

  • --append — is it okay to append features onto layer(s) that already exist? Yes? Okay then. This will also create the output dataset if it's not there yet. 💖
  • --co, --creation-option <NAME>=<VALUE> — lots of formats have optional dataset creation options, and they control the little particulars of the file you're making. For example, the GeoPackage driver has creation options that control the version. 👑

May be repeated. ♻️

Which dataset creation options exist depends totally on the format driver, and some simple formats have no creation options at all. You can list the options a format supports with the --formats command line option, but the format's own documentation is the definitive source of info on driver creation options. Go read the Vector drivers format specific documentation for what's legal per format. 📚

And note: dataset creation options are different from layer creation options. Don't mix them up bestie, they're not the same girl. 🙈

  • --if, --input-format <format> — the format/driver name to attempt to open the input file(s) with. Usually you don't need this, but it's there so you can skip automatic driver detection when that detection is being messy and picking the wrong driver. You can repeat it several times to name several candidate drivers. Fair warning: it does not force those drivers to open the dataset. And some drivers have opinions about file extensions, lowkey. 👀

May be repeated. ♻️

  • --input-layer <INPUT-LAYER> — names one or more layers to process. If you say nothing, every layer gets processed. All of them. The whole squad. 🌈
  • --lco, --layer-creation-option <NAME>=<VALUE> — lots of formats have optional layer creation options, and they control the particulars of the layer you create. For example, the GeoPackage driver has layer creation options that control the feature identifier or geometry column name, or set the identifier or description, etc. 💫

May be repeated. ♻️

Which layer creation options exist depends on the format driver, and some simple formats have no layer creation options at all. You can list a format's supported options with the --formats command line option, but the format's documentation is the definitive source on driver creation options. Check the Vector drivers format specific documentation for what's legal per format. 📚

Again, hello: layer creation options are different from dataset creation options. 💅

  • --no-create-empty-layers — Added in version 3.13. Avoid creating layers that no features will ever be written to. No ghost layers, no empty vibes, we're not doing that. 🚫👻
  • --oo, --open-option <NAME>=<VALUE> — dataset open option (format specific). 🫶

May be repeated. ♻️

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output vector format are we using? Allowed values may be given by gdal --formats | grep vector | grep rw | sort ⭐
  • --output-layer <NAME> — names the layer the features get written into. If you don't specify it, the output layer names will be the same as the input layer names. Copy-paste energy, and we respect it. 🎀
  • --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. If you don't pass it, then by default gdal errors out when the target file or dataset already exists. So if you see that error: that's not a bug, that's --overwrite missing. 😌
  • --overwrite-layer — is overwriting the existing output vector layer allowed? 👑
  • --skip-errors — Added in version 3.12. Should failures to write feature(s) just be ignored? Maybe! But heads up, this sets the transaction unit size to one feature at a time, which may cause severe slowdown when inserting into databases. It's giving "convenient but you will feel it" 💀
  • --update — open an existing output dataset in update mode? Yes/no. 🔄
  • --upsert — Added in version 3.12. it's a variant of --append where the OGRLayer::UpsertFeature() operation is used to insert or update features, instead of appending with OGRLayer::CreateFeature(). 🧚

Currently this is 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).

Upsert uses the FID of the input feature as the key for updating existing features — when the FID is set, and the FID column name is not the empty string. It is crucial to make sure the FID in the source and target layers are consistent. Seriously. Don't skip that check. 😭

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. 🌸

  • -q, --quiet — suppress the progress bar and some warning messages. Shhh. 🤫

💖 RETURN STATUS CODE 💖

The program returns status code 0 when it succeeds, and non-zero when there's an error (non-blocking errors emitted as warnings are considered a successful execution, so don't panic over those 🫶).

🌈 EXAMPLES 🌈

⭐ Example 1: Converting file poly.shp to a GeoPackage

$ gdal vector convert poly.shp output.gpkg

⭐ Example 2: Add new layer from file line.shp to an existing GeoPackage, and rename it "lines"

$ gdal vector convert --update --output-layer=lines line.shp output.gpkg

⭐ Example 3: Append features from from file poly2.shp to an existing layer poly of a GeoPackage, without a progress bar

$ gdal vector convert --quiet --append --output-layer=poly poly2.shp output.gpkg

👑 AUTHOR 👑

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's the whole page, bestie!! 💜 This one comes from the GDAL source, version-flavored and dated Aug 18, 2026 — go convert something gorgeous with it. 🦋✨

📦 where this page comes from