osmflex

A Django app that mirrors pgosm-flex output, giving you an ORM-shaped view of OpenStreetMap data imported via osm2pgsql.

Stack

Python 3.11+
Django 5.2 LTS
PostGIS 16-3.4+
Package managed with uv

Install

uv add osmflex

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    ...,
    "django.contrib.gis",
    "osmflex",
]

Import OSM data

osmflex ships two management commands:

./manage.py run_osm2pgsql /path/to/foo.osm.pbf   # writes schema osm.*
./manage.py import_from_pgosmflex --truncate     # upserts into osmflex_*

Then query with the Django ORM:

>>> from osmflex.models import AmenityPoint
>>> AmenityPoint.objects.count()
14827
>>> AmenityPoint.objects.tagged()[:5]  # annotates each row with the full OSM tag JSONB

End-to-end runnable example: examples/minimal_import/ walks through fetching a Geofabrik extract and running the full pipeline in a disposable PostGIS container. Try:

cd examples/minimal_import
make db-up install migrate pbf import psql

Docs

docs/architecture.md — the pgosm-flex → Django pipeline, taxonomy, SRID choice, how upsert_sql mangles source-table names, how to add your own Osm subclass.
docs/api.md — cheatsheet of every public export.

Prerequisites

osm2pgsql ≥ 1.6 — install via package manager (sudo apt install osm2pgsql on modern Ubuntu; brew install osm2pgsql on macOS) or build from source.
PostGIS — 3.4+ recommended.
The bundled pgosm-flex LUA config in osmflex/management/flex-config/ is sourced from rustprooflabs/pgosm-flex.

Development

uv sync --dev
uv run pytest              # 24 tests
uv run ruff check .
uv run mypy osmflex

Releasing

Releases are automated via .github/workflows/release.yml using PyPI Trusted Publishing (OIDC). To cut a release:

Bump version in pyproject.toml on main; merge.
Tag the merged commit with the same version (no v prefix):
```
git tag 0.3.1 && git push origin 0.3.1
```
The workflow verifies tag/pyproject match, builds sdist + wheel, publishes to PyPI, and creates a GitHub Release with generated notes.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

osmflex-0.3.1.tar.gz (92.9 kB view details)

Uploaded Jul 7, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

osmflex-0.3.1-py3-none-any.whl (49.6 kB view details)

Uploaded Jul 7, 2026 Python 3

File details

Details for the file osmflex-0.3.1.tar.gz.

File metadata

Download URL: osmflex-0.3.1.tar.gz
Upload date: Jul 7, 2026
Size: 92.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for osmflex-0.3.1.tar.gz
Algorithm	Hash digest
SHA256	`f85d6ee8a8f34b1d3c33753a3b6cddba50671c44a739b360f6489676c11e4b6d`
MD5	`f12fdc20b44eb8cf961be99253711a93`
BLAKE2b-256	`6b646856b673fd28bc72d9b0f9e308fd82314b6091894bfcb67cb8f03c8ae0d1`

See more details on using hashes here.

Provenance

The following attestation bundles were made for osmflex-0.3.1.tar.gz:

Publisher: release.yml on catalpainternational/osm2django

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: osmflex-0.3.1.tar.gz
- Subject digest: f85d6ee8a8f34b1d3c33753a3b6cddba50671c44a739b360f6489676c11e4b6d
- Sigstore transparency entry: 2098371448
- Sigstore integration time: Jul 7, 2026
Source repository:
- Permalink: catalpainternational/osm2django@427f291f956803f6ff23041142358a4f12e17535
- Branch / Tag: refs/tags/0.3.1
- Owner: https://github.com/catalpainternational
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@427f291f956803f6ff23041142358a4f12e17535
- Trigger Event: push