pbf

OpenStreetMap PBF golang encoder/decoder

A golang based OpenStreetMap PBF encoder/decoder with a handy command line utility, pbf.

Development

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.

Go Version Support

• 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, and 1.26.x.
• go.mod currently declares go 1.23; this is a compatibility floor, while active support is the CI-verified window above.
• Bug reports should include go version output so compatibility issues can be reproduced quickly.

pbf Command Line Utility

The pbf CLI can be installed using the go install command:

$ go install m4o.io/pbf/v2/cmd/pbf

pbf info

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.