GDAL-VECTOR-MAKE-VALID(1)

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

👑 GDAL-VECTOR-MAKE-VALID(1)

okay so bestie, welcome to the GDAL-VECTOR-MAKE-VALID(1) page, straight out of the GDAL manual 💖 pull up a chair, grab a strawberry 🍓, because this one fixes your broken geometries and honestly it's giving main character energy.

✨ NAME ✨

gdal-vector-make-valid — Fix validity of geometries of a vector dataset 🦋

Added in version 3.12. (yes, she's new, she's fresh, she's iconic 💅)

🎀 SYNOPSIS 🎀

Usage: gdal vector make-valid [OPTIONS] <INPUT> <OUTPUT>

Fix validity of geometries 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 [not available in pipelines]
  --skip-errors                                        Skip errors when writing features [not available in pipelines]
  --active-layer <ACTIVE-LAYER>                        Set active layer (if not specified, all)
  --active-geometry <ACTIVE-GEOMETRY>                  Geometry field name to which to restrict the processing (if not specified, all)
  --method <METHOD>                                    Algorithm to use when repairing invalid geometries.. METHOD=linework|structure (default: linework)
  --keep-lower-dim                                     Keep components of lower dimension after MakeValid()

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

and now let's walk through every single one of those flags, because we do not gatekeep here 🫶

Positional arguments 🌟

  • -i, --input <INPUT> — the input vector datasets 📥 required, and ngl it is not available in pipelines.
  • -o, --output <OUTPUT> — the output vector dataset 📤 also required, also not available in pipelines.

Common Options 💖

  • -h, --help — shows the help message and then dips. bye 👋
  • --json-usage — prints the usage as a JSON document and exits. machine-readable slay 🤖✨
  • --config <KEY>=<VALUE> — a configuration option. may be repeated, so stack 'em 🧚
  • -q, --quiet — quiet mode: no progress bar, no warning message. silence is golden 🔇 (also 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> — the output format, and yes "GDALG" is allowed here 👀 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 an 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 one, babe, you can't have both 💀
  • --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 you don't specify it, it's all of them.
  • --active-geometry <ACTIVE-GEOMETRY> — the geometry field name to restrict the processing to. if you don't specify it, again, it's all of them.
  • --method <METHOD> — the algorithm to use when repairing invalid geometries. METHOD=linework|structure, and the default is linework.
  • --keep-lower-dim — keep components of lower dimension after MakeValid(). (more on this queen below 👇)

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, choose one bestie 💅

🌈 DESCRIPTION 🌈

gdal vector make-valid makes sure your geometries are actually valid according to the rules of the Simple Features specification. no more chaotic polygons running around unchecked, periodt ✋

Here's the tea on what it actually runs: the OGRGeometry::MakeValid() operation, followed by OGRGeometryFactory::removeLowerDimensionSubGeoms() — unless you set --keep-lower-dim, in which case that second step does not happen.

It can also be used as a step of gdal vector pipeline. very demure, very composable 🎀

NOTE: This command requires a GDAL build against the GEOS</> library. no GEOS, no make-valid, so check that build bestie 😭

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

okay this part is genuinely iconic. this program supports serializing the command line as a JSON file using the GDALG output format ✨

That resulting file can then be opened as a vector dataset using the GDALG: GDAL Streamed Algorithm driver, and it'll apply the specified pipeline in an on-the-fly / streamed way. like, your whole command as a dataset. no cap, it's giving pipeline-in-a-file 💖

💅 PROGRAM-SPECIFIC OPTIONS 💅

--keep-lower-dim

Keep components of lower dimension after MakeValid().

so here's the situation: MakeValid() may hand you back a GeometryCollection of a Polygon and a LineString from a Polygon input 🫠 by default, only the Polygon would be returned. But set this option and you get the whole GeometryCollection back instead. keep the little bits, they matter 🥺

--method=linework|structure

Algorithm to use when repairing invalid geometries.

  • the default linework method combines all rings into a set of noded lines and then extracts valid polygons from that linework. this method keeps all input vertices. nothing gets dropped, she's thorough 🌸
  • the structure method (only available with GEOS >= 3.10) first makes all rings valid, then merges shells and subtracts holes from shells to generate a valid result. it assumes that holes and shells are correctly categorized — so don't come for her if your data is messy 🙈

for examples of the differences between these methods, see Geometry Validity.

and that's only part 1, bestie — there's more coming, don't go anywhere 👑

✨ STANDARD OPTIONS ✨

okay bestie these are the universal ones, the options that show up across basically all the gdal vector subcommands, so learn them once and you're set 💅

  • --active-geometry <ACTIVE-GEOMETRY> — names the active geometry field, by, like, its actual name. Once you set it, only that geometry field gets processed — every other geometry field just sits there untouched, minding its own business. Don't set it and it's game on for all the geometry fields, no cap. You can totally pair this with --active-layer for max targeting precision 🎯
  • --active-layer <ACTIVE-LAYER> — picks the active layer, by name. Specify it and only that one layer gets processed, all the other layers are left completely alone (they're giving bystander energy). Skip it and every layer gets processed. ngl it's that simple 🦋
  • --append — says whether appending features to existing layer(s) is allowed. Bonus: it also creates the output dataset for you if it doesn't already exist. iconic behavior honestly ✨
  • --co, --creation-option <NAME>=<VALUE> — lots of formats have optional dataset creation options, and these let you control the lil specifics of the file being created. Like, the GeoPackage driver supports creation options to control the version, yk?

May be repeated. (yes, you can stack them 🫶)

Which dataset creation options exist totally depends on the format driver, and some simple formats have none at all — nothing, zero, tragic. You can list the options a format supports with the --formats command line option, but fr fr the format's own documentation is the definitive source for driver creation options. Go check the Vector drivers format-specific docs for the legal creation options per format.

Heads up bestie: dataset creation options are not the same thing as layer creation options. Do not mix them up, I'm begging 🙈
  • --if, --input-format <format> — the format/driver name you want it to try when opening the input file(s). Usually you don't even need this, but it's a lifesaver for skipping automatic driver detection when that detection fails to pick the right driver. Repeat it as many times as you want to line up several candidate drivers. Note though — it doesn't force those drivers to open the dataset. Some drivers have requirements on file extensions and will simply not cooperate 💀

May be repeated.

  • --input-layer <INPUT-LAYER> — names one or more layers to process. Default vibe is: all layers get processed. But if you wanna read and write all the layers while only processing a subset, use --active-layer instead 🌸
  • --lco, --layer-creation-option <NAME>=<VALUE> — many formats have optional layer creation options that control the particulars of the layer being created. For example, the GeoPackage driver supports layer creation options for controlling the feature identifier or geometry column name, setting the identifier or description, etc. so many choices ✨

May be repeated.

Which layer creation options exist varies by format driver, and some simple formats have none 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 of truth for driver creation options. Peep the Vector drivers format-specific documentation for the legal creation options for each format.

And again: layer creation options ≠ dataset creation options. Different things, bestie, don't conflate them 💅
  • --oo, --open-option <NAME>=<VALUE> — dataset open option (format specific).

May be repeated.

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output vector format you wanna use. Wanna see the allowed values? Run:
gdal --formats | grep vector | grep rw | sort

and boom, there's your list 📋

  • --output-layer <NAME> — names the layer that features get written to. If you don't specify it, output layer names just mirror the input layer names. easy 💁‍♀️
  • --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. Without it, the default is that gdal errors out if the target already exists. so, yk, only reach for this if you mean it 🔥
  • --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 just be ignored. But listen — this option sets the size of the transaction unit to one feature at a time, which may cause severe slowdown when inserting into databases. So it's giving "convenient but maybe don't" 😭

  • --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 gets used to insert or update features instead of appending with OGRLayer::CreateFeature().

rn 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, iykyk 👑)

The upsert operation uses the FID of the input feature, when it's 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. fr fr, do not skip this step.

For the GPKG driver, you can also 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's a UNIQUE column that isn't the integer primary key. slay 🌈

💫 RETURN STATUS CODE 💫

The program returns status code 0 in case of success, and non-zero in case of error. And hey, non-blocking errors that get emitted as warnings still count as a successful execution, so don't panic over those 🫶

🎀 EXAMPLES 🎀

Example 1: Basic use of make-valid

$ gdal vector make-valid in.gpkg out.gpkg --overwrite

the classic. one line, in, out, overwrite. beautiful 🌸

👑 AUTHOR 👑

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's a wrap on GDAL-VECTOR-MAKE-VALID(1) bestie!! 🦋✨ this version dropped Aug 18, 2026, and it's part of the GDAL fam. go forth and make those geometries valid, you absolute icon 💅💜

📦 where this page comes from