OSMIUM-FILE-FORMATS(5)

💖 OSMIUM-FILE-FORMATS 💖

okay bestie, so this is the page for osmium-file-formats — the ✨manual page✨ (that's the (5) vibe, iykyk) that spills all the tea about every OSM file format the Osmium fam actually knows how to read and write. sit down, grab a boba, we're doing this 💅

---

🌸 NAME 🌸

osmium-file-formats — the OSM file formats that Osmium is aware of. no cap, that's the whole name, that's the whole job 🫶

---

🎀 FILE TYPES 🎀

so OSM uses three types of files for its main character data:

💾 Data files

these are the ones you'll see literally everywhere. they hold the OSM data from one specific point in time — could be a whole planet file with all the OSM data, could be some kind of extract. at most one version of every object (node, way, or relation) lives in this file. deleted objects? not invited, they're not in here. the usual suffix is .osm. periodt.

🕰️ History files

these ones are giving archive energy — they've got the current version of an object plus its whole history. so for any object (node, way, or relation) there can be zero or more versions in this file. deleted objects <em>can</em> also be in here. the usual suffix is .osm or .osh. and here's the annoying part — because sometimes the same suffix as normal data files (.osm) gets used, and because there's no clear indicator in the header, it's not always clear what type of file you're actually looking at 😭 like babe, it could be either, we just don't know.

🔄 Change files

sometimes called diff files or replication diffs, these babies contain the changes between one state of the OSM database and another state. change files can contain several versions of an object and also deleted objects. the usual suffix is .osc.

---

all these files have one thing in common: they contain OSM objects (nodes, ways, and relations). history files and change files can contain several versions of the same object and also deleted objects — data files can't, bestie, it's just not their thing.

where possible, Osmium commands can handle all file types. for some commands only some file types make sense. slay, that's just how it is 💅

---

🌈 FORMATS 🌈

the osmium command line tool supports all the major OSM file formats plus some more. here's the lineup:

• the classical XML format in the variants .osm (for data files), .osh (for data files with history) and .osc (for change files). ✨
• the PBF binary format (usually with suffix .osm.pbf or just .pbf). 💜
• the OPL format (usually with suffix .osm.opl or just .opl). 🎀
• the O5M/O5C format (usually with suffix .o5m or .o5c) — reading only, so don't come for it expecting to write. 🙈
• the “debug” format (usually with suffix .osm.debug) — writing only. 💀

and bonus: files in all formats except PBF can be compressed using gzip or bzip2. just add .gz or .bz2 suffixes, respectively. iconic behavior honestly 🦋

---

🧚 AUTODETECTION 🧚

which format a file has is usually autodetected from the file name suffix. the vibes do the work for you ✨

but if that doesn't work — whether because you're reading from STDIN or writing to STDOUT, or because you have an unusual file name — you have to set the format manually. you can also set the format manually if you want to specify special format options. main character energy, you take control 💅

most osmium commands support the --input-format/-F and --output-format/-f options to set the format. they take a comma-separated list of arguments, the first is the format, further arguments set additional options.

---

👑 SPECIAL FORMAT OPTIONS 👑

these options can be added when writing OSM files:

• history=true/false — explicitly set whether this file allows multiple versions of the same object or not. by default it's set to true for .osh and .osc files, and to false otherwise.
• xml_change_format=true/false — enable/disable XML change format. same as .osc.
• force_visible_flag=true/false (default: false) — force writing of visible flag, even for normal OSM XML files.
• pbf_dense_nodes=true/false (default: true) — enable/disable DenseNodes format for PBF files.
• pbf_compression=none/zlib/lz4 (default: zlib) — set compression type in PBF files. zlib (or true) is the default and almost all files use this. none (or false) disables compression, which will make writing files a bit faster, but the resulting files are 2 to 3 times bigger. the lz4 compression is not quite as good as zlib but much faster to compress and decompress — it is currently not supported by most OSM file readers.
• pbf_compression_level=... — set compression level for PBF. available values and default depend on the compression type used, see the OSM File Formats Manual for details.
• add_metadata=true/false/... (default: true) — enable/disable writing of object metadata such as changeset id, username, etc. disabling this will make files a bit smaller. this can also be set to other values, see the OSM File Formats Manual for details.
• locations_on_ways=true/false (default: false) — add node locations to way nodes. (PBF, XML, OPL only.)
• use_color=true/false (default: false) — output with ANSI colors. (DEBUG format only.)
• add_crc32=true/false (default: false) — add CRC32 checksum to all objects. (DEBUG format only.)

---

⭐ EXAMPLES ⭐

here are some examples, bestie:

• pbf — PBF format.
• pbf,add_metadata=false — PBF format, don't write metadata.
• osm.bz2 — XML format, compressed with bzip2.
• osc.gz — OSM change file, compressed with gzip.
• osm.gz,xml_change_format=true — OSM change file, compressed with gzip.
• osh.opl — OSM history file in OPL format.

---

🦋 SEE ALSO 🦋

• osmium(1)
• Osmium website
• OSM File Formats Manual

---

💜 COPYRIGHT 💜

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 osmium-file-formats version 1.19.1 of the manual, and it's yours truly signing off 💖✨ go read a planet file, hydrate, and stan autodetection. bye!! 🎀🦋💅