osmium

library4.3.1pypypi✓ verified 85d ago

PyOsmium provides Python bindings for libosmium, a high-performance C++ library designed for processing OpenStreetMap (OSM) data. It enables efficient reading, writing, and manipulation of various OSM file formats (PBF, XML, O5M) and change files, making it suitable for large-scale geospatial data tasks. The library is actively maintained with regular updates, typically aligning with new libosmium releases, and is currently at version 4.3.1.

data

pip install osmium

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · OSMIUM

osmium

datapythonv4.3.1

Install

2.3s avg

Import

—

Disk

24MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

build_error

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.3s · import 0.000s · 26MB

24MB installed

● package 24MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SimpleHandler

✓ from osmium import SimpleHandler

FileProcessor

✓ from osmium import FileProcessor

Node

✓ from osmium.osm import Node

Location

✓ from osmium.osm import Location

SimpleWriter

✓ from osmium import SimpleWriter

This example demonstrates how to use `osmium.SimpleHandler` to process an OSM PBF file. It creates a temporary dummy PBF file, then defines a handler to count nodes, ways, and relations, and applies it to the file. This pattern is fundamental for reading and iterating over OSM data.

import osmium import osmium.osm import tempfile import os from datetime import datetime # Create a dummy PBF file for demonstration purposes # In a real scenario, you'd process an existing .osm.pbf file. temp_pbf_file = os.path.join(tempfile.gettempdir(), "test.osm.pbf") writer = osmium.SimpleWriter(temp_pbf_file) writer.add_node(osmium.osm.Node(1, location=osmium.osm.Location(1.0, 1.0), user='test_user', timestamp=datetime.now())) writer.add_node(osmium.osm.Node(2, location=osmium.osm.Location(2.0, 2.0), user='test_user', timestamp=datetime.now())) writer.add_way(osmium.osm.Way(3, nodes=[1, 2], user='test_user', timestamp=datetime.now())) writer.add_relation(osmium.osm.Relation(4, user='test_user', timestamp=datetime.now())) writer.close() class ElementCounter(osmium.SimpleHandler): def __init__(self): super().__init__() self.nodes = 0 self.ways = 0 self.relations = 0 def node(self, n): self.nodes += 1 def way(self, w): self.ways += 1 def relation(self, r): self.relations += 1 try: # Process the (dummy) PBF file using the handler handler = ElementCounter() handler.apply_file(temp_pbf_file) print(f"Nodes: {handler.nodes}") print(f"Ways: {handler.ways}") print(f"Relations: {handler.relations}") finally: # Clean up the temporary file if os.path.exists(temp_pbf_file): os.remove(temp_pbf_file)

Debug

Known issues

breakingPrior to v4.0.0, PyOsmium loaded entire OSM files into memory, which was inefficient for large files. Version 4.0.0 introduced `osmium.FileProcessor` for iterative processing. Scripts written for older versions that implicitly assumed full in-memory loading will likely fail or be extremely slow with large datasets.

fix

Rewrite processing logic to use `osmium.FileProcessor` for efficient, iterative handling of large OSM files. For simpler cases, `osmium.SimpleHandler.apply_file()` is still available and performs iterative processing.

affects: <4.0.0

gotchaObjects (Node, Way, Relation) passed to handler callbacks are only valid for the duration of that specific callback. Keeping direct Python references to these objects beyond the callback's scope will lead to errors, as the underlying C++ memory is deallocated. This is a common source of `TypeError: cannot convert 'osmium._osmium.Node' object to Python type`.

fix

If you need to persist data from an OSM object, you must copy the relevant attributes (e.g., `node.id`, `node.tags`, `node.location`) into new Python objects or data structures, rather than storing the `osmium.osm.Node` itself.

affects: All versions

deprecatedThe method `ReplicationServer.open_url()` was deprecated in favor of `ReplicationServer.set_request_parameter()` in v3.7.0. Direct overrides of `open_url()` are no longer supported, making old custom replication logic incompatible.

fix

Update custom `ReplicationServer` implementations to use `set_request_parameter()` for configuring HTTP requests instead of overriding `open_url()`.

affects: >=3.7.0

breakingVersion 4.3.0 removed the direct dependency on Boost C++. While this simplifies the build process, custom C++ extensions or very specific build environments that previously relied on PyOsmium's Boost dependency might need adjustments.

fix

Ensure your build environment is updated. If you have custom C++ components interacting with PyOsmium's internals, review their Boost dependencies. For most users installing via pip, this change is transparent.

affects: >=4.3.0

breakingThe build process for installing PyOsmium from source changed significantly in v4.1.0. `pybind11` is now installed from PyPI, and custom location variables for `libosmium`, `protozero`, or `boost` (e.g., `LIBOSMIUM_PREFIX`) have been replaced by CMake's standard `Libosmium_ROOT`, `Protozero_ROOT` variables.

fix

When installing from source, update your build scripts or commands to use the new CMake `_ROOT` variables for custom component locations.

affects: >=4.1.0

breakingVersion 4.3.1 fixed a critical regression introduced in `libosmium` 2.23.0 (used by PyOsmium 4.3.0) where deletions in extract diffs were not handled correctly. Users processing OSM change files, especially for extracts like those from Geofabrik, might encounter incorrect data if using earlier versions.

fix

Upgrade to PyOsmium 4.3.1 or later immediately if you are working with change files for OSM data extracts.

affects: 4.3.0

Errors

Common errors & fixes

TypeError: cannot convert 'osmium._osmium.Node' object to Python type

Attempting to store a direct reference to an Osmium C++ object (like Node, Way, Relation) outside of its handler callback, leading to access violations once the underlying C++ memory is deallocated.

fix

Instead of storing the entire Osmium object, extract and store only the necessary data (e.g., `node.id`, `node.tags.get('name')`, `node.location`) into a new Python dictionary or custom object.

AttributeError: 'FileProcessor' object has no attribute 'apply_file'

Confusing the `osmium.FileProcessor` class (used for advanced, granular processing of file sections) with the `apply_file()` method, which belongs to `osmium.SimpleHandler`.

fix

For basic file processing using a handler, instantiate your custom handler and call `handler.apply_file(filename)`. `FileProcessor` is used differently, typically with a `osmium.apply()` function or by managing its processing stages explicitly.

FileNotFoundError: [Errno 2] No such file or directory: 'your_file.osm.pbf'

The specified OpenStreetMap data file (.osm.pbf, .osm, .o5m, etc.) does not exist at the given path, or the path is incorrect/inaccessible.

fix

Verify that the file path is correct and absolute, or that the file exists in the current working directory. Ensure the Python process has read permissions for the file.

Upgrade

Version history

4.3.1latest on PyPI · released Apr 2, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/osmcode/pyosmium ↗

packagehttps://pypi.org/project/osmium/ ↗

homepagehttps://osmcode.org/pyosmium ↗

docshttps://docs.osmcode.org/pyosmium/latest/ ↗