OSMIUM-SORT(1)

📦
version 1.19.1 · 6 versions
, in fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking

✨ OSMIUM-SORT ✨

okay so bestie, say hi to osmium-sort, the part of the osmium family that sorts OSM files. this is the osmium-sort(1) manual, and yes we're reading it together, no skimming 💅

🎀 NAME 🎀

osmium-sort — sort OSM files. that's it. that's the whole job. and it does it flawlessly obviously.

🦋 SYNOPSIS 🦋

osmium sort [OPTIONS] OSM-FILE...

🌸 DESCRIPTION 🌸

so what it does: it combines and sorts the content of <em>all</em> the input files you hand it on the command line. all of them. together. as one. slay 🫶

Objects get sorted by type, then ID, then version. and here's the lil twist that trips people up — IDs are sorted negative IDs first, then positive IDs, and <em>both</em> of those groups are ordered by their absolute values. so yeah, -1 comes before -2, bestie. it's giving "math class but make it fashion".

so the sort order for types and IDs goes like this:

node -1, node -2, ..., node 1, node 2, ..., way -1, way -2, ..., way 1, way 2, ..., relation -1, relation -2, ..., relation 1, relation 2, ...

if there are several objects of the same type and the same ID, they get ordered by ascending version. ✨

and if there are several objects of the same type, same ID, <em>and</em> same version? the sort order is unspecified. it's giving chaos, honestly. also, heads up: duplicate objects will not be removed. no deduping, no cleaning up after you, it just sorts. periodt.

this command works with normal OSM data files, history files, and change files. versatile queen 👑

and the streaming situation — this command reads its input file(s) only once and writes its output file in one go, so it can be streamed, ie. it can read from STDIN and write to STDOUT. (unless the multipass strategy is used, but more on that in a sec 👀)

💅 OPTIONS 💅

  • -s, --strategy=STRATEGY — the sorting strategy, aka how we're doing this. the simple strategy reads all input files into memory, does the sorting, and writes everything out. the multipass strategy reads the input files in three passes — one for nodes, one for ways, and one for relations. after reading all objects of each type, they get sorted and written out. it's a bit slower than simple, but it uses less memory. heads up tho: multipass doesn't work when reading from STDIN. default: simple.

🌈 COMMON OPTIONS 🌈

  • -h, --help — show usage help. your lil map when you're lost 🗺️
  • -v, --verbose — set verbose mode. the program will output information about what it is doing to STDERR. it's basically narrating its own life 💬
  • --progress — show progress bar. usually a progress bar is only displayed if STDOUT and STDERR are detected to be a TTY. with this option a progress bar is always shown. note that a progress bar will never be shown when reading from STDIN or a pipe.
  • --no-progress — do not show progress bar. usually a progress bar is displayed if STDOUT and STDERR are detected to be a TTY. with this option the progress bar is suppressed. note that a progress bar will never be shown when reading from STDIN or a pipe.

🍓 INPUT OPTIONS 🍓

  • -F, --input-format=FORMAT — the format of the input file(s). use it to set the input format if it can't be autodetected from the file name(s). this sets 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. use it 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. making sure it's really really there 💾
  • --generator=NAME — the name and version of the program generating the output file. it gets 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. protective king 🛡️
  • --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.

💀 DIAGNOSTICS 💀

osmium sort exits with exit code

  • 0 — if everything went alright 🎉
  • 1 — if there was an error processing the data 😭
  • 2 — if there was a problem with the command line arguments 🙈

🧚 MEMORY USAGE 🧚

osmium sort keeps the contents of all the input files in main memory. and babes, this will take roughly 10 times as much memory as the files take on disk in .osm.bz2 or osm.pbf format. plan accordingly, your RAM is not infinite bestie 😭

⭐ EXAMPLES ⭐

sort in.osm.bz2 and write out to sorted.osm.pbf:

osmium sort -o sorted.osm.pbf in.osm.bz2

iconic. ate. no notes.

🔥 SEE ALSO 🔥

Copyright (C) 2013-2026 Jochen Topf <jochen@topf.org>.

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 the whole page, bestie 💜 this was version 1.19.1 of the osmium-sort(1) manual — go sort something iconic, ily, bye 🎀✨

📦 where this page comes from