GDAL-VECTOR-CONCAT(1)

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

okay so welcome to GDAL-VECTOR-CONCAT(1) 💅 the manual page for gdal-vector-concat — yes it's a whole handshake, that's just how man pages are. strap in bestie, we're concatenating 🦋

🌸 NAME 🌸

gdal-vector-concat — Concatenate vector datasets.

Added in version 3.11. ✨ (so she's new-new, not a legacy icon, we love a fresh drop)

💖 SYNOPSIS 💖

Usage: gdal vector concat [OPTIONS] <INPUTS>... <OUTPUT>

Concatenate vector datasets.

🎀 Positional arguments

  • -i, --input <INPUTS> — the input vector datasets. [1.. values], [required], [not available in pipelines]. You need at least one, no skipping, bestie.
  • -o, --output <OUTPUT> — the 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]. For when you want her to stop yapping.

🔥 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]. Yes that's four aliases, she contains multitudes.
  • --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 — pick a lane, they can't both go.
  • --skip-errors — Skip errors when writing features. [not available in pipelines].
  • --mode <MODE> — Determine the strategy to create output layers from source layers. MODE=merge-per-layer-name|stack|single (default: merge-per-layer-name).
  • --output-layer <OUTPUT-LAYER> — Name of the output vector layer (single mode), or template to name the output vector layers (stack mode).
  • --source-layer-field-name <SOURCE-LAYER-FIELD-NAME> — Name of the new field to add to contain identification of the source layer, with value determined from 'source-layer-field-content'.
  • --source-layer-field-content <SOURCE-LAYER-FIELD-CONTENT> — A string, possibly using {AUTO_NAME}, {DS_NAME}, {DS_BASENAME}, {DS_INDEX}, {LAYER_NAME}, {LAYER_INDEX}.
  • --field-strategy <FIELD-STRATEGY> — How to determine target fields from source fields. FIELD-STRATEGY=union|intersection (default: union).
  • -s, --input-crs <INPUT-CRS> — Input CRS.
  • -d, --output-crs <OUTPUT-CRS> — Output CRS.

🦋 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 — again, choose one, we're not doing both.

👑 DESCRIPTION 👑

gdal vector concat concatenates several source datasets. That's her whole job. She takes your little datasets and she makes them one big dataset. glow up 💅

It has 3 main modes:

  • --mode = merge-per-layer-name (the default). The output dataset generated by the command will contain as many layers as there are different layer names in the source datasets. For example if there are 2 datasets, one with layers a and b, and the other one with layers b and c, 3 output layers will be created: a, b (merging the 2 source layers) and c.
  • --mode = stack. The output dataset generated by the command will contain as many layers as there are layers in the source datasets. For example if there are 2 datasets ds1 (with layers a and b) and ds2 (with layers b and c), 4 output layers will be created: ds1_a, ds1_b, ds2_b and ds2_c.
  • --mode = single. The output dataset generated by the command will contain one single layer, merging all layers in the source datasets.

When an output layer merges several source layer, by default the resulting schema will contain the union of all source fields. It is possible to select only the intersection with the --field-strategy set to intersection. Regarding the resulting CRS, by default the CRS of the source layer will be used as the target CRS, and features of other source layers that do no match this CRS will be reprojected to it. --output-crs can be used to select a given destination CRS.

This command can also be used as the first step of gdal vector pipeline. she's a team player, she plays well with others 🫶

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

streamed. on-the-fly. no waiting around for a full materialization. it's giving efficiency ⭐

🧚 PROGRAM-SPECIFIC OPTIONS 🧚

--field-strategy union|intersection

Determines how the schema of the target layer is built from the schemas of the input layers:

  • union (default) to use a super-set of all the fields from all source layers. everyone's invited, bring your whole field list
  • intersection to use a sub-set of all the common fields from all source layers. only the fields everybody agreed on — very exclusive guest list

--input-crs, -s <INPUT-CRS>

Set (override) input spatial reference. If not specified the SRS found in the input dataset will be used.

The coordinate reference systems that can be passed are anything supported by the OGRSpatialReference.SetFromUserInput() call, which 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.

If the SRS has an explicit vertical datum that points to a geoid grid, and the input dataset is a single band dataset, a vertical correction will be applied to the values of the dataset.

--mode merge-per-layer-name|stack|single

Determine the strategy to create output layers from source layers. See introductory paragraph for more details. (yes bestie, scroll up, the 3 modes are right there 💖)

--output-crs, -d <OUTPUT-CRS>

Set output spatial reference. Inputs will be reprojected to this CRS if necessary.

The coordinate reference systems that can be passed are anything supported by the OGRSpatialReference.SetFromUserInput() call, which 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.

If the SRS has an explicit vertical datum that points to a geoid grid, and the input dataset is a single band dataset, a vertical correction will be applied to the values of the dataset.

--output-layer <OUTPUT-LAYER>

Name of the output vector layer (in single mode, and the default is "merged"), or template to name the output vector layers in stack mode (the default value is {AUTO_NAME}). Not allowed in merge-per-layer-name mode. not allowed. she said what she said. 💀

The template in stack mode can be a string with the following variables that will be substituted with a value computed from the input layer being processed:

  • {AUTO_NAME}: equivalent to {DS_BASENAME}_{LAYER_NAME} if both values are different, or {LAYER_NAME} when they are identical (case of shapefile).
  • {DS_NAME}: name of the source dataset
  • {DS_BASENAME}: base name of the source dataset
  • {DS_INDEX}: index of the source dataset
  • {LAYER_NAME}: name of the source layer
  • {LAYER_INDEX}: index of the source layer

--source-layer-field-content <SOURCE-LAYER-FIELD-CONTENT>

If specified, the schema of the target layer will be extended with a new field (whose name is given by --source-layer-field-name, or source_ds_lyr otherwise), whose content is determined by the specified template (see --output-layer for variables that can be used). yes, go read --output-layer again, the variables are all up in there ✨

--source-layer-field-name <SOURCE-LAYER-FIELD-NAME>

If specified, the schema of the target layer will be extended with a field whose name is the value of this option and whose content is determined --source-layer-field-content. pair them up like besties, they're a set 🫶

✨ STANDARD OPTIONS ✨

Okay bestie, these are the options basically every gdal vector command shares, so if you've met one of them before, it's the same queen every time 💅

  • --append — says whether we're allowed to append features to existing layer(s). Bonus: it also creates the output dataset if it isn't there yet. So it's giving "come through, we'll build it if we have to" energy 🫶
  • --co, --creation-option <NAME>=<VALUE> — dataset creation options, aka the little knobs lots of formats have so you can fine-tune the file being created. Like, the GeoPackage driver has creation options that control the version, iykyk.

You can repeat this one as many times as you want.

Which creation options exist depends entirely on the format driver, and some simple formats have literally none, no cap. You can get a list of supported options with the --formats command line option, but — and this is important — the documentation for the format is the definitive source of truth for driver creation options. Go check the Vector drivers format specific documentation for the legal creation options of each format.

Heads up: dataset creation options are not the same as layer creation options. Different thing, different vibe, don't mix them up 🙈
  • --if, --input-format <format> — the format/driver name you want tried when opening the input file(s). Usually you don't need it, but it's clutch when automatic driver detection fails to pick the right driver and you need to skip it. You can repeat this several times to line up several candidate drivers. Note: it does not force those drivers to open the dataset — some drivers have requirements on file extensions, so no promises boo.

You can repeat this one.

  • --input-layer <INPUT-LAYER> — picks the name of one or more layers to process. Default? All layers get processed, periodt.
  • --lco, --layer-creation-option <NAME>=<VALUE> — layer creation options, which control particulars about the layer created. The GeoPackage driver, for example, has layer creation options for the feature identifier or geometry column name, setting the identifier or description, all of that.

You can repeat this one too.

Again, which layer creation options exist varies by format driver, and some simple formats have none at all. --formats can list options supported for a format, but the format documentation is the definitive source. Check the Vector drivers format specific documentation for the legal creation options per format.

And yes: layer creation options are different from dataset creation options. Same warning, opposite direction 😭
  • --oo, --open-option <NAME>=<VALUE> — dataset open option, and it's format specific.

You can repeat this one.

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output vector format you want. The allowed values can be listed with:
gdal --formats | grep vector | grep rw | sort
  • --output-open-option, --output-oo <NAME>=<VALUE> — added in version 3.12 ⭐

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

You can repeat this one.

  • --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. It's giving protective, honestly 💖
  • --overwrite-layer — says whether overwriting the existing output vector layer is allowed.
  • --skip-errors — added in version 3.12 ✨

Says whether failures to write feature(s) should just be ignored. But be careful 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. She said "correct but slow" 💀

  • --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().

Right now this is implemented only in a few drivers: GPKG — GeoPackage vector, Elasticsearch: Geographically Encoded Objects for Elasticsearch, and MongoDBv3. So 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. Like, do not play with this one 🙏

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. And no, the non-blocking errors emitted as warnings don't count against you — those are considered a successful execution 🫶

🎀 EXAMPLES 🎀

Example 1: Creating a GeoPackage stacking all input shapefiles in separate layers.

gdal vector concat --mode=stack *.shp out.gpkg

Example 2: Adding a field to indicate the source layer, and reprojecting to a single CRS

Concatenate the content of france.shp and germany.shp into merged.shp, reprojecting them to ETRS89, and add a 'country' field to each feature whose value is 'france' or 'germany' depending on where it comes from:

gdal vector concat --mode=single --source-layer-field-name=country --output-crs=EPSG:4258 france.shp germany.shp merged.shp

👑 AUTHOR 👑

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's the whole page bestie, you ate 🍓 the source is GDAL and this version is dated Aug 18, 2026 — go forth and concat, mwah 💅✨

📦 where this page comes from