OSMIUM-EXTRACT(1)

📦

version 1.19.1 · 6 versions

1.19.1 · fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking (latest)
1.14.0 · ubuntu jammy
1.16.0 · ubuntu noble
1.15.0 · debian bookworm
1.19.0 · fedora 44, ubuntu resolute
1.18.0 · debian trixie, fedora 43, ubuntu questing

, in fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking

✨ OSMIUM-EXTRACT(1) ✨

okay bestie, sit down, hydrate, because this is the osmium-extract manual page and it's a whole journey. 💖

🌸 NAME 🌸

osmium-extract — create geographical extracts from an OSM file

no cap, that's literally the whole job description.

🦋 SYNOPSIS 🦋

osmium extract --config CONFIG-FILE [OPTIONS] OSM-FILE
osmium extract --bbox LEFT,BOTTOM,RIGHT,TOP [OPTIONS] OSM-FILE
osmium extract --polygon POLYGON-FILE [OPTIONS] OSM-FILE

three ways in, pick your fighter. 💅

💜 DESCRIPTION 💜

So basically you're making geographical extracts out of an OSM data file or an OSM history file. The region (that's the geographical extent, iykyk) can be handed to you as a bounding box or as a (multi)polygon. 🗺️

There are three ways of calling this command:

Specify a config file with the --config/-c option. It can define any number of regions you want to cut out. See the CONFIG FILE section for details. 👑
Specify a bounding box to cut out with the --bbox/-b option.
Specify a (multi)polygon to cut out with the --polygon/-p option.

The input file is assumed to be ordered in the usual order: nodes first, then ways, then relations. that's just the vibe, don't fight it. 🌈

If the --with-history/-H option is used, the command will work correctly for history files. This currently works for the complete_ways strategy only. The simple or smart strategies do not work with history files. A history extract will contain every version of all objects with at least one version in the region. Generating a history extract is somewhat slower than a normal data extract. 😭 (slow but correct, we respect it)

Osmium will make sure that all nodes on the vertices of the boundary of the region will be in the extract, but nodes that happen to be directly on the boundary, but between those vertices, might end up in the extract or not. In almost all cases this will be good enough, but if you want to make really sure you got everything, use a small buffer around your region. 🫶

ngl this is the part everyone gets confused about, so read it twice: boundary-vertex nodes = guaranteed in. random nodes sitting on the boundary between vertices = ✨mystery✨. want certainty? buffer your region.

By default no bounds will be set in the header of the output file. Use the --set-bounds option if you need this.

Note that osmium extract will never clip any OSM objects, ie. it will not remove node references outside the region from ways or unused relation members from relations. This means you might get objects that are not reference-complete. It has the advantage that you can use osmium merge to merge several extracts without problems. 🔥 (not reference-complete is a feature here, bestie, not a bug)

🎀 OPTIONS 🎀

-b, --bbox=LONG1,LAT1,LONG2,LAT2 — Set the bounding box to cut out. Can not be used with --polygon/-p, --config/-c, or --directory/-d. The coordinates LONG1,LAT1 are from one arbitrary corner, the coordinates LONG2,LAT2 are from the opposite corner. so like, corner to corner, you got this 🧚
-c, --config=FILE — Set the name of the config file. Can not be used with the --bbox/-b or --polygon/-p option. If this is set, the --output/-o and --output-format/-f options are ignored, because they are set in the config file. 🙈 (the config file is the main character here, sorry to -o and -f)
--clean=ATTR — Clean the attribute (version, timestamp, changeset, uid, user), from the data before writing it out again. The attribute will be set to 0 (the user will be set to the empty string). This option can be given multiple times. Depending on the output format these attributes might show up as 0 or not show up at all. 💀
-d, --directory=DIRECTORY — Output directory. Output file names in the config file are relative to this directory. Overwrites the setting of the same name in the config file. This option is ignored when the --bbox/-b or --polygon/-p options are used, set the output directory and name with the --output/-o option in that case.
-H, --with-history — Specify that the input file is a history file. The output file(s) will also be history file(s). 🕰️
-p, --polygon=POLYGON_FILE — Set the polygon to cut out based on the contents of the file. The file has to be a GeoJSON, poly, or OSM file as described in the (MULTI)POLYGON FILE FORMATS section. It has to have the right suffix to be detected correctly. Can not be used with --bbox/-b, --config/-c, or --directory/-d. ⚠️ right suffix or it simply won't get detected, periodt.
-s, --strategy=STRATEGY — Use the given strategy to extract the region. For possible values and details see the STRATEGIES section. Default is “complete_ways”. ✨
-S, --option=OPTION=VALUE — Set a named option for the strategy. If needed you can specify this option multiple times to set several options.
--set-bounds — Set the bounds field in the header. The bounds are set to the bbox or envelope of the polygon specified for the extract. Note that strategies other than “simple” can put nodes outside those bounds into the output file. 👀 (yes, outside. it's giving chaotic but it's documented.)

💖 COMMON OPTIONS 💖

-h, --help — Show usage help. 🫶
-v, --verbose — Set verbose mode. The program will output information about what it is doing to STDERR.

🌈 INPUT OPTIONS 🌈

-F, --input-format=FORMAT — The format of the input file(s). Can be used to set the input format if it can't be autodetected from the file name(s). This will set the format for all input files, there is no way to set the format for some input files only. See osmium-file-formats(5) or the libosmium manual for details. 💅

🍓 OUTPUT OPTIONS 🍓

-f, --output-format=FORMAT — The format of the output file. Can be used to set the output file format if it can't be autodetected from the output file name. See osmium-file-formats(5) or the libosmium manual for details.
--fsync — Call fsync after writing the output file to force flushing buffers to disk. 🔥
--generator=NAME — The name and version of the program generating the output file. It will be added to the header of the output file. Default is “osmium/” and the version of osmium.
-o, --output=FILE — Name of the output file. Default is - (STDOUT). 👑
-O, --overwrite — Allow an existing output file to be overwritten. Normally osmium will refuse to write over an existing file. 🙅♀️ no consent, no overwrite.
--output-header=OPTION=VALUE — Add output header option. This command line option can be used multiple times for different OPTIONs. See the osmium-output-headers(5) man page for a list of available header options. For some commands you can use the special format “OPTION!” (ie. an exclamation mark after the OPTION and no value set) to set the value to the same as in the input file. ⭐

okay that's the setup, the lore. more parts incoming, don't go anywhere bestie 🦋

✨ CONFIG FILE ✨

okay so bestie, the config file is literally the main character here — it tells osmium-extract which files to make and which regions to cut out. 💖

It's in JSON format, no cap. The top-level is an object that contains at least an “extracts” array. It can also have a “directory” entry that names the directory where all the output files will be created:

{
    "extracts": [...],
    "directory": "/tmp/"
}

The extracts array is the whole point — it specifies the extracts that should be created. Each item in the array is an object with at least a name “output” naming the output file, and a region defined in a “bbox”, “polygon” or “multipolygon” name. You can add an optional “description” — the program won't use it, but it helps document what's inside the file. You can also add an optional “output_format” if the format can't be detected from the “output” file name. Run osmium help file-formats to get a description of allowed formats. 🫶

The optional “output_header” lets you set additional OSM file header settings, like the “generator”. If you set the value of a file header setting to null, the output header will be set to the same header from the input file. Iconic behaviour, honestly.

"extracts": [
    {
        "output": "hamburg.osm.pbf",
        "output_format": "pbf",
        "description": "optional description",
        "bbox": ...
    },
    {
        "output": "berlin.osm.pbf",
        "description": "optional description",
        "polygon": ...
    },
    {
        "output": "munich.osm.pbf",
        "output_header": {
            "generator": "MyExtractor/1.0",
            "osmosis_replication_timestamp": null
        },
        "description": "optional description",
        "multipolygon": ...
    }
]

There are several formats for specifying the regions, and they all have their own vibe:

bbox

A bounding box in one of two formats. The first is a simple array with four real numbers — the first two specify the coordinates of an arbitrary corner, the second two specify the coordinates of the opposite corner. Slay.

{
    "output": "munich.osm.pbf",
    "description": "Bounding box specified in array format",
    "bbox": [11.35, 48.05, 11.73, 48.25]
}

The second format uses an object instead of an array:

{
    "output": "dresden.osm.pbf",
    "description": "Bounding box specified in object format",
    "bbox": {
        "left": 13.57,
        "right": 13.97,
        "top": 51.18,
        "bottom": 50.97
    }
}

polygon

A polygon, either specified inline in the config file or read from an external file. See the (MULTI)POLYGON FILE FORMATS section for external files. If specified inline, this is a nested array — the outer array defines the polygon, the next array is the rings, and the innermost arrays are the coordinates. This format is the same as in GeoJSON files. 💅

In this example there's only one outer ring:

"polygon": [[
    [9.613465, 53.58071],
    [9.647599, 53.59655],
    [9.649288, 53.61059],
    [9.613465, 53.58071]
]]

In each ring, the last set of coordinates should be the same as the first set, closing the ring. Periodt.

multipolygon

A multipolygon, either specified inline in the config file or read from an external file. See the (MULTI)POLYGON FILE FORMATS section for external files. If specified inline, this is a nested array — the outer array defines the multipolygon, the next array is the polygons, the next is the rings, and the innermost arrays are the coordinates. Same format as GeoJSON files. 🌸

In this example there's one outer and one inner ring:

"multipolygon": [[[
    [6.847, 50.987],
    [6.910, 51.007],
    [7.037, 50.953],
    [6.967, 50.880],
    [6.842, 50.925],
    [6.847, 50.987]
],[
    [6.967, 50.954],
    [6.969, 50.920],
    [6.932, 50.928],
    [6.934, 50.950],
    [6.967, 50.954]
]]]

In each ring, the last set of coordinates should be the same as the first set, closing the ring. Again. 🎀

okay real talk — Osmium must check each and every node in the input data and find out in which bounding boxes or (multi)polygons this node is. This is very cheap for bounding boxes, but more expensive for (multi)polygons. And it gets more expensive the more vertices the (multi)polygon has. So use bounding boxes or simplified polygons where possible, bestie. Your CPU will thank you. 😭

another thing — bounding boxes or (multi)polygons are not allowed to span the -180/180 degree line. If you need that, cut out the regions on each side and use osmium merge to join the resulting files. No cap.

🦋 (MULTI)POLYGON FILE FORMATS 🦋

External files describing a (multi)polygon are specified in the config file using the “file_name” and “file_type” properties on the “polygon” or “multipolygon” object:

"polygon": {
    "file_name": "berlin.geojson",
    "file_type": "geojson"
}

If file names don't start with a slash (/), they're interpreted relative to the directory where the config file is. If the “file_type” is missing, Osmium will try to autodetect it from the suffix of the “file_name”. Lowkey magical, highkey useful. ✨

The following file types are supported:

geojson — GeoJSON file containing exactly one Feature of type Polygon or MultiPolygon, or a FeatureCollection with the first Feature of type Polygon or MultiPolygon. Everything except the actual geometry (of the first Feature) is ignored. 🙈
poly — A poly file as described in https://wiki.openstreetmap.org/wiki/Osmosis/Polygon_Filter_File_Format. This wiki page also mentions several sources for such poly files. 👑
osm — An OSM file containing one or more multipolygon or boundary relation together with all the nodes and ways needed. Any OSM file format (XML, PBF, ...) supported by Osmium can be used here, but the correct suffix must be used, so the file format is detected correctly. Files for this can easily be obtained by searching for the area on OSM and then downloading the full relation using a URL like https://www.openstreetmap.org/api/0.6/relation/RELATION-ID/full. Or you can use osmium getid -r to get a specific relation from an OSM file. Note that both these approaches can get you very detailed boundaries which can take quite a while to cut out. Consider simplifying the boundary before use. 💀

If there are several (multi)polygons in a poly file or OSM file, they will be merged. The (multi)polygons must not overlap, otherwise the result is undefined. fr fr, don't do it. 🚫

💅 STRATEGIES 💅

okay bestie so osmium extract has ✨options✨ for how it makes your extracts, and depending on which one you pick, different objects end up in the output. They all differ in how much memory they eat and how many times they gotta re-read the input file. So like… the strategy you choose depends on how you're gonna use the extracts, plus how much memory and time you've got lying around. 🫶

The default strategy is complete_ways. periodt.

Strategy `simple` 🌸

Runs in a single pass. The extract will contain all nodes inside the region and all ways referencing those nodes, as well as all relations referencing any nodes or ways already included. Ways crossing the region boundary will not be reference-complete. Relations will not be reference-complete. This strategy is fast because it reads the input only once, but ngl the result is not enough for most use cases. It's the only strategy that will work when reading from a socket or pipe. 🚰 And heads up — this strategy will not work for history files. 💀

Strategy `complete_ways` 👑

Runs in two passes. The extract will contain all nodes inside the region and all ways referencing those nodes, as well as all nodes referenced by those ways. The extract will also contain all relations referenced by nodes inside the region or ways already included and, recursively, their parent relations. The ways are reference-complete, but the relations are not. 🎀

Strategy `smart` 🧠✨

Runs in three passes. The extract will contain all nodes inside the region and all ways referencing those nodes, as well as all nodes referenced by those ways. The extract will also contain all relations referenced by nodes inside the region or ways already included and, recursively, their parent relations. The extract will also contain all nodes and ways (and the nodes they reference) referenced by relations tagged type=multipolygon that directly reference any nodes in the region, or ways referencing nodes in the region. The ways are reference-complete, and all multipolygon relations referencing nodes in the region, or ways that have nodes in the region, are reference-complete. Other relations are not reference-complete. 💅

For the complete_ways strategy you can set the option -S relations=false, in which case no relations will be written to the output file. 🙈

The smart strategy allows the following strategy options:

Use -S types=TYPE,... to change the types of relations that should be reference-complete. Instead of just relations tagged type=multipolygon, you can either get all relations (use -S types=any) or give a list of types to the -S option: -S types=multipolygon,route. Note that especially boundary relations can be huge, so if you include them, be aware your result might be huge. 😭
Use -S complete-partial-relations=X to force completion of partly completed relations. If this is set, all relations that have more than X percent of their members already in the extract will have their full set of members in the extract. So this allows completing almost-complete relations. It can be useful, for instance, to make sure a boundary relation is complete even if some of it is outside the polygon used for extraction. 🦋
Use -S tags=PATTERN,... to only complete relations that have a tag matching one of the *PATTERN*s. So for example if you use -S tags=landuse,natural=wood,natural=water, everything tagged landuse=* or natural=wood or natural=water is added to the result, but no other relations. 🌈

You can combine the -S types, -S complete-partial-relations, and -S tags options. The options will be interpreted as (types OR complete-partial-relations) AND tags. 🔥

🩺 DIAGNOSTICS 🩺

osmium extract exits with exit code

0 — if everything went alright, 💖
1 — if there was an error processing the data, or
2 — if there was a problem with the command line arguments, config file or polygon files. 💀

🧠 MEMORY USAGE 🧠

Memory usage of osmium extract depends on the number of extracts and on the strategy used. For the simple strategy it will at least be the number of extracts times the highest node ID used, divided by 8. For complete_ways, twice that. And for the smart strategy, a bit more. 🫠

If you want to split a large file into many extracts, do this in several steps. First create several larger extracts and then split them again and again into smaller pieces. trust the process bestie 🎀

🚧 LIMITS 🚧

You can not have more than 500 extracts. Although chances are that you will be running out of memory long before that. See MEMORY USAGE. 😭

✨ EXAMPLES ✨

See the example config files in the extract-example-config directory. To try it:

osmium extract -v -c extract-example-config/extracts.json \
    germany-latest.osm.pbf

Extract the city of Karlsruhe using a boundary polygon:

osmium extract -p karlsruhe-boundary.osm.bz2 germany-latest.osm.pbf \
    -o karlsruhe.osm.pbf

Extract the city of Munich using a bounding box:

osmium extract -b 11.35,48.05,11.73,48.25 germany-latest.osm.pbf \
    -o munich.osm.pbf

👀 SEE ALSO 👀

osmium(1), osmium-file-formats(5), osmium-output-headers(5), osmium-getid(1), osmium-merge(1)
Osmium website

License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. ⚖️

📬 CONTACT 📬

If you have any questions or want to report a bug, please go to <https://osmcode.org/contact.html>

👑 AUTHORS 👑

Jochen Topf <jochen@topf.org>.

and that's a wrap bestie 💖 this whole thing is from version 1.19.1, and the page itself is dated OSMIUM-EXTRACT(1) — go forth and extract, you absolute icon 🎀✨

📦 where this page comes from

fedora 44: osmium-tool 1.19.1-1.fc44 · GPL-3.0-only
nixos 26.05: osmium-tool 1.19.1
nixpkgs unstable: osmium-tool 1.19.1
ubuntu stonking: osmium-tool 1.19.1-1 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms