PySide6-OsmAnd-SDK is an independent GitHub project for bringing OsmAnd's native map stack into modern Qt6 and PySide6 workflows. It combines vendored OsmAnd core sources, Windows build tooling, native widget integration, and a runnable preview application in one repository, making it easier to build and embed offline map capabilities from a single codebase.
Author: OliverZhaohaibin
- ports the OsmAnd Qt5-era native map stack to Qt6
- makes the native C++ map widget usable from PySide6 applications
- supports offline rendering based on OsmAnd
.obfmap data - includes both native OpenGL preview and Python-driven raster preview paths
- provides build scripts for Windows (MinGW, MSVC) and Linux (GCC, Clang) toolchains
- bundles demo data and OsmAnd resources for local testing and integration work
output.mp4
This project is aimed at developers who want the strengths of OsmAnd's map engine while building with modern Qt and Python tools. It reduces the friction of combining C++ map rendering with a PySide6 user interface, and provides a practical foundation for desktop map viewers, GIS tools, travel applications, and other offline-first location products.
By moving the native stack forward to Qt6 and validating PySide6 compatibility, the repository helps make OsmAnd-based development more accessible to teams working on current-generation Qt applications instead of older Qt5-only integrations.
vendor/osmand/build: build tree and supporting files used by the Windows-oriented OsmAnd build flowvendor/osmand/core: vendored OsmAnd core sourcesvendor/osmand/core-legacy: vendored legacy core sources still required by the native buildvendor/osmand/resources: OsmAnd rendering resources, styles, and data filestools/osmand_render_helper_native: native helper and widget sources plus MinGW and MSVC build scriptssrc/maps: PySide6 preview application and Python integration layersrc/maps/main.py: preview entry point
- native
osmand_native_widget.dllhosting through PySide6 - helper-backed Python raster rendering for
.obf - OpenGL and non-OpenGL preview widgets
- bundled
World_basemap_2.obfdemo data for immediate testing
OsmAnd .obf files are offline binary map packages. They store the map data consumed by the native engine, including vector features such as roads, boundaries, landuse, water, place labels, routing-related information, and points of interest. In this repository, the preview uses the bundled src/maps/tiles/World_basemap_2.obf file so the project can be run and demonstrated immediately.
The bundled .obf file is only a default demo dataset. You can replace it with another OsmAnd .obf file, select a different file from the preview window, or point the runtime to a custom path through the documented environment variables. Additional .obf downloads are available from the official OsmAnd download list: https://download.osmand.net/list.php.
Rendering styles are XML-based rule files located under vendor/osmand/resources/rendering_styles, usually named like default.render.xml, mapnik.render.xml, or snowmobile.render.xml. These files control how the same .obf data is visualized, including colors, line rules, polygon fills, icons, labels, and theme-specific display logic. The Python integration layer passes both the selected .obf data source and the active style file into the OsmAnd rendering backend, which makes it possible to switch presentation without changing the underlying map data.
Together, .obf data files and rendering style files form the core of the offline map pipeline in this project: the .obf file provides the geographic content, and the style file defines how that content appears on screen.
- Install Python dependencies:
python -m pip install -e .- Build at least one runtime:
powershell -ExecutionPolicy Bypass -File tools\osmand_render_helper_native\build_helper.ps1or:
powershell -ExecutionPolicy Bypass -File tools\osmand_render_helper_native\build_native_widget_msvc.ps1- Launch the preview:
osmand-preview --backend autoYou can also run the entry point directly:
python src\maps\main.py --backend auto- Install system dependencies:
# Ubuntu/Debian
sudo apt-get install build-essential cmake git qt6-base-dev libqt6opengl6-dev
# Fedora/RHEL
sudo dnf install gcc g++ cmake git qt6-qtbase-devel qt6-qtbase-gui qt6-qtdeclarative-devel
# Arch
sudo pacman -S base-devel cmake git qt6-base- Install Python dependencies:
python -m pip install -e .- Build the helper:
bash tools/osmand_render_helper_native/build_linux.sh- Launch the preview:
osmand-preview --backend autoYou can also run the entry point directly:
python src/maps/main.py --backend auto- the preview defaults to the bundled
src/maps/tiles/World_basemap_2.obfand the vendored resources undervendor/osmand/resources - the bundled
.obfis replaceable, so you can test other OsmAnd map extracts downloaded from download.osmand.net/list.php - Windows: helper outputs in
tools/osmand_render_helper_native/distandtools/osmand_render_helper_native/dist-msvcare generated and ignored by Git - Linux: helper outputs in
tools/osmand_render_helper_native/dist-linuxare generated and ignored by Git - when the native widget runtime is available, the preview can use the embedded OsmAnd widget; otherwise the Python rendering path remains available
- on Linux, the native widget library is built as a
.sofile (shared object); the Python path remains the recommended approach for Linux deployments - if you embed the native widget on Linux and hit XCB/GLX issues, see BUILD.md and the Python SDK Guide for the entry-point Qt runtime flags to apply before
QApplicationstarts
Because this repository redistributes vendored OsmAnd source trees, the top-level project is documented as GPL-3.0-or-later.
Top-level license files:
LICENSE: project-level license summary forPySide6-OsmAnd-SDKCOPYING: verbatim GNU GPL v3 text
The vendored upstream trees keep their own original license files:
vendor/osmand/core/LICENSEvendor/osmand/core-legacy/LICENSEvendor/osmand/resources/LICENSE
Additional context is summarized in NOTICE.md.