OpenStreetMap PBF golang encoder/decoder
A golang based OpenStreetMap PBF encoder/decoder with a handy command line utility, pbf.
This repository includes a Codex-friendly workflow:
$ make fmt
$ make test
$ make test-race
$ make test-integration
$ make lint
$ make verify
Project-specific agent guidance is documented in AGENTS.md.
The Makefile uses a project-local .cache/ directory for Go and lint caches to
keep local and sandboxed runs reproducible; .cache/ is intentionally ignored
by git.
- Supported window: the Go release from approximately one year ago through latest stable.
- As of February 26, 2026, CI-verified versions are
1.24.x,1.25.x, and1.26.x. go.modcurrently declaresgo 1.23; this is a compatibility floor, while active support is the CI-verified window above.- Bug reports should include
go versionoutput so compatibility issues can be reproduced quickly.
The pbf CLI can be installed using the go install command:
$ go install m4o.io/pbf/v2/cmd/pbf
The pbf CLI can be used to obtain summary and extended information about an
OpenStreetMap PBF file:
$ pbf info -i testdata/greater-london.osm.pbf
BoundingBox: [(51.69344, -0.511482) (51.28554, 0.335437)]
RequiredFeatures: OsmSchema-V0.6, DenseNodes
OptionalFeatures:
WritingProgram: Osmium (http://wiki.openstreetmap.org/wiki/Osmium)
Source:
OsmosisReplicationTimestamp: 2014-03-24T21:55:02Z
OsmosisReplicationSequenceNumber: 0
OsmosisReplicationBaseURL:
JSON output can be obtained by adding the -j option:
$ pbf info -j -i testdata/greater-london.osm.pbf | jq
{
"BoundingBox": {
"Left": -0.511482,
"Right": 0.33543700000000004,
"Top": 51.69344,
"Bottom": 51.285540000000005
},
"RequiredFeatures": [
"OsmSchema-V0.6",
"DenseNodes"
],
"OptionalFeatures": null,
"WritingProgram": "Osmium (http://wiki.openstreetmap.org/wiki/Osmium)",
"Source": "",
"OsmosisReplicationTimestamp": "2014-03-24T14:55:02-07:00",
"OsmosisReplicationSequenceNumber": 0,
"OsmosisReplicationBaseURL": ""
}
Here, jq is used to pretty print the compact JSON.
Extended information about the OpenStreetMap PBF file can be obtained
by using the -e option. This causes the entire file to be scanned, which can
take a very long time; a progress bar is displayed on stderr.
$ pbf info -e -i testdata/greater-london.osm.pbf
BoundingBox: [(51.69344, -0.511482) (51.28554, 0.335437)]
RequiredFeatures: OsmSchema-V0.6, DenseNodes
OptionalFeatures:
WritingProgram: Osmium (http://wiki.openstreetmap.org/wiki/Osmium)
Source:
OsmosisReplicationTimestamp: 2014-03-24T21:55:02Z
OsmosisReplicationSequenceNumber: 0
OsmosisReplicationBaseURL:
NodeCount: 2,729,006
WayCount: 459,055
RelationCount: 12,833
Finally, pbf can read an OpenStreetMap PBF file from stdin:
$ cat testdata/greater-london.osm.pbf | pbf info -e
In this case, a progress bar is not displayed since there is no way to know, a priori, what the size of the PBF file is.
