Command line¶
Every duckosm command and its options. duckosm <command> --help prints the same list;
duckosm --version prints the version. -h is short for --help everywhere.
| Group | Commands |
|---|---|
| Build and areas | build, init-config, boundary, clip-pbf, extract |
| Query and inspect | way |
| Maps and routing | viz, route-map |
| Exports | sumo, matsim, matsim-lanes, gmns, gmns-map, gmns-viz, export-gis, gis-debug, export-graph |
| Experimental and lane-level | opendrive, lanelet2, railml, lane-graph, route-lanes |
| Enrich a built database | elevation, admin, multimodal |
DB is a built duckOSM database; GMNS_DB is a database written by gmns. Commands that
enrich a database (elevation, admin, multimodal) change it in place.
Build and areas¶
build¶
Builds a network from a PBF, or cuts one from a built database. Guide: Build a network.
duckosm build [OPTIONS]
| Option | Does | Default |
|---|---|---|
-c, --config PATH |
a config file. An option below that you type overrides the file | |
-p, --pbf PATH |
input .osm.pbf |
|
-o, --output PATH |
output file | <name>.duckdb, named after the boundary file, else the PBF, else the --source-db file |
-b, --boundary PATH |
GeoJSON area to build | none: the whole PBF |
--source-db PATH |
cut from this built database instead of a PBF (how) | |
--h3-cell TEXT |
build the area of this H3 cell: its outline is the boundary | |
--graph / --no-graph |
build edge_graph, the graph of legal turns |
on |
--h3-index / --no-h3-index |
add H3 cell ids to nodes and edges | on |
--h3-resolution INTEGER |
H3 resolution, 0–15 | 8 |
-m, --modes TEXT |
driving, walking or cycling; repeat for several |
driving |
--features / --no-features |
build the base-map layers, features.* |
on |
--levels / --no-levels |
the last step: the drawing order of the roads (visualization.edge_levels), with your edits kept |
on |
--fixes FILE |
a rules file of fixes for OSM errors; overrides the config's osm_overrides key |
none |
--log-file FILE |
also write the log to this file | console only |
With none of -c, -p and --source-db, it uses config/default.yaml if that file exists.
init-config¶
Writes the commented config template, to edit and build from. Guide: With a config file.
duckosm init-config [OPTIONS] [PATH]
| Option | Does | Default |
|---|---|---|
PATH |
the file to write | duckosm.yaml |
--force |
overwrite PATH if it exists |
boundary¶
Finds the boundary of an area by name and writes it as GeoJSON: first in the PBF's own borders (offline), then with Nominatim (online). Guide: Prepare an area.
duckosm boundary [OPTIONS] [NAME]
| Option | Does | Default |
|---|---|---|
--pbf PATH |
search the borders in this PBF first; needs GDAL's ogr2ogr |
|
--osm-id INTEGER |
take this OSM boundary relation (when a name matches several) | |
--offline |
never ask Nominatim | |
-o, --out FILE |
output GeoJSON | <name>.geojson |
clip-pbf¶
Cuts a PBF down to a GeoJSON area, with osmium. Guide:
Cut a smaller PBF.
duckosm clip-pbf [OPTIONS] PBF BOUNDARY
| Option | Does | Default |
|---|---|---|
-o, --out FILE |
output PBF | <boundary name>.osm.pbf |
--strategy |
complete_ways: a way that crosses the border is kept whole; smart: also completes multipolygons (rivers, land cover), for base-map layers; simple: cuts ways at the border |
complete_ways |
extract¶
Cuts one area out of a built database into a new database, by name, OSM id or GeoJSON. Edge ids are kept. Guide: Several areas from one region.
duckosm extract --source SOURCE --db DB (--name NAME | --osm-id OSM_ID | --boundary BOUNDARY)
| Option | Does | Default |
|---|---|---|
--source SOURCE |
the built database to cut from | required |
--db DB |
the new database (overwritten) | required |
--name NAME |
the area, by name in the source's admin_boundaries (add them) |
one of the three |
--osm-id OSM_ID |
the area, by its admin_boundaries OSM id |
one of the three |
--boundary BOUNDARY |
the area, as a GeoJSON file | one of the three |
Query and inspect¶
info¶
Prints what a built database holds: per mode its edges, nodes, private edges, km, legal turns
(edge_graph) and turn restrictions; when and by which duckOSM version it was built; its time zone;
and the other schemas (raw OSM data, base-map layers, mm, boundary, elevation, drawing order). Reads only.
duckosm info [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
--json |
print one JSON object instead of a table |
$ duckosm info monaco.duckdb
monaco.duckdb (built 2026-10-01 18:20, duckOSM 0.1.0; time zone Europe/Monaco)
mode edges nodes private_edges km edge_graph turn_restrictions
driving 2,765 1,719 214 92.6 4,953 38
walking 10,952 4,116 154 244.1 32,476 -
cycling 10,274 4,151 133 245.5 28,851 -
also: raw (OSM data), features (11 layers), mm (across modes), boundary
A database built before this command existed has no build date; the rest is the same.
way¶
Prints everything the database knows about one OSM way: its raw row, then its edges in every mode,
in order. A negative OSM_ID shows connector edges.
Guide: Look up one OSM way.
duckosm way [OPTIONS] DB OSM_ID
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
modes to include; repeat for several | every mode in the db |
--geom / --no-geom |
add the edge geometry as WKT | off |
-o, --out PATH |
write the table to a .csv, .parquet or .json file instead of printing it |
|
--json |
print one JSON object: the raw way (tags, refs) and its edges |
Maps and routing¶
viz¶
Draws the maps of a built network with mapstyle: one page with
every mode and one per mode, over the database's own base map. Needs duckosm[viz]. Guide:
Draw a map.
duckosm viz [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
only these modes' pages; repeat for several | every mode's page, plus <name>_map.html with all modes |
--basemap TEXT |
a background from the web: voyager, positron, osm, satellite, … |
none: the database's own layers |
--out-dir TEXT |
output folder; files are <name>_map.html and <name>_<mode>_network.html |
reports |
--arrows / --no-arrows |
one-way arrows, shown when zoomed in | on |
--boundary / --no-boundary |
draw main.boundary, if there is one |
on |
--google-3d / --no-google-3d |
a Google 3D window linked to the map. It needs a Google Maps key in GOOGLE_MAPS_KEY, and the page must be served over http at an address on the key's website list |
on when GOOGLE_MAPS_KEY is set |
levels¶
Makes and solves the level area of the database and stores the drawing order in it (schema visualization): every road gets a casing number
(start, main, end), a fill number and its ends as drawn. The roads of all modes go into one level area folder next to the database (DB.levels), where your edits.csv,
heads.csv and caps.csv are written from the tables visualization.level_* of the database (they are the master); roadstyle solves it with them. duckosm build does this as its last step; this command makes it again, or later for a build with --no-levels. The database is
changed in place. To fix places by hand: roadstyle-levels edit DB.levels. Needs duckosm[levels]. Guide: Store the drawing order.
duckosm levels [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
--area DIR |
the level area folder | DB.levels next to the database |
levels-edit¶
The level editor of the database: fix which road is drawn over which (bridges, crossings) and the head and the cap of a road end. It is
roadstyle's editor, started on the area of the file, with mapstyle's base map (water, land, buildings,
railways, signals) and every road of the file: the roads of its modes and their private_edges (bus, private, pedestrian, delivery). The roads that no mode can use are coloured as on the maps: private grey, bus lanes blue, pedestrian streets lavender, delivery streets tan. With GOOGLE_MAPS_KEY set, the editor has the Google 3D window and Street View Linked; the key's website list must have the editor's address (http://localhost:8000/*, the same as for the maps). A file with one mode gives
an editor of that mode; with several modes, the editor's boxes show only some. The work folder is written from the tables visualization.level_* (they are the
master), and solved first if the stored numbers are not those of the roads in the file. At each Apply the editor writes your edits and the new drawing order into the
file. Needs duckosm[levels]; the layers need duckosm[viz]. Guide: Store the drawing order.
duckosm levels-edit [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
--area DIR |
the work folder, rewritten from the tables of the database | DB.levels next to the database |
--port INTEGER |
the editor is at http://localhost:PORT/, and the maps of --reports on the same port: one port for ever, so a Google key's website list needs one address (http://localhost:8000/*) |
8000 |
--reports DIR |
a folder of maps (duckosm viz), served as files at the same port; any other address is the editor |
reports |
--plain |
no base-map layers: the editor as roadstyle draws it | off |
bus¶
Matches the database's OSM bus route relations to its driving edges and writes schema bus: bus.routes (one row per route, with
its gaps) and bus.route_edges (the edges each route travels, in order). A build from a PBF does it too (options.bus_routes); this adds it to a file built
before. The database is changed in place. Needs raw.* and the driving network. How: Bus routes.
duckosm bus DB
route-map¶
Writes duckOSM's route planner over a map drawn by mapstyle: drag a start and an end, pick Drive,
Walk, Cycle or Walk + drive. Routing runs in the browser with the same answers as route_points()
and directions(). Walk + drive needs multimodal first. Needs duckosm[viz]. Guide:
On a map.
duckosm route-map [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
-m, --mode [driving\|walking\|cycling\|walk+drive] |
the first choice and the mode in front (walk+drive: every mode; needs multimodal); the page offers every mode |
the first mode, walking in front |
--basemap TEXT |
a background from the web: voyager, positron, osm, satellite, … |
none: the database's own layers |
--google-3d / --no-google-3d |
a Google 3D window linked to the map. It needs a Google Maps key in GOOGLE_MAPS_KEY, and the page must be served over http |
on when GOOGLE_MAPS_KEY is set |
-o, --out TEXT |
output HTML | reports/<name>_route_map.html |
Exports¶
sumo¶
Writes a SUMO network; the SUMO edge id is the edge_id. Page: SUMO.
duckosm sumo [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
the mode | driving |
--out-dir TEXT |
output folder | sumo |
--name TEXT |
file name base | the db file name |
--connections / --no-connections |
write the allowed turns from edge_graph; off lets netconvert guess them |
on |
-c, --config PATH |
a netconvert config (.netccfg) instead of the built-in one |
|
--netconvert / --no-netconvert |
build the .net.xml with netconvert; off writes only the plain XML files |
on |
matsim¶
Writes a MATSim network.xml; link ids are edge_ids. Page: MATSim.
duckosm matsim [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
a mode, a comma list (driving,cycling) or all: one network with modes per link |
driving |
--crs TEXT |
projected CRS for node coordinates | UTM zone of the data |
--gzip / --no-gzip |
gzip the file | on |
-o, --out TEXT |
output file | <name>_network.xml.gz |
matsim-lanes¶
Writes MATSim lanes.xml and signal files from a GMNS database. The signal timing is a placeholder.
Page: Lanes and signals.
duckosm matsim-lanes [OPTIONS] GMNS_DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
the GMNS mode | driving |
--signals / --no-signals |
also write signalSystems, signalGroups, signalControl.xml |
on |
--cycle INTEGER |
signal cycle length, seconds | 90 |
-o, --out TEXT |
output folder | . |
gmns¶
Writes a GMNS database: nodes, links, lanes, movements, signals; link_id is the edge_id.
Page: GMNS.
duckosm gmns [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
-o, --out TEXT |
output database | <name>_gmns.duckdb |
-m, --mode TEXT |
modes; repeat for several | every mode in the db |
--to-csv TEXT |
also write the standard GMNS CSV files to this folder | |
--lane-geometry / --no-lane-geometry |
compute a line for each lane (needs shapely) | on |
--meso |
also build the meso (lane-level) network, meso_<mode> |
|
--meso-mode TEXT |
modes for --meso; repeat for several |
driving |
--micro |
also build the micro (cell) network, micro_<mode> |
|
--micro-mode TEXT |
modes for --micro; repeat for several |
driving |
--combined |
also write gmns_all, one network for all modes |
|
--drive-side |
right or left: the side two-way lanes are drawn on |
right |
gmns-map¶
Writes an HTML map of a GMNS database with lanestyle:
every lane at its width, on a base map. Needs pip install "duckosm[viz]". Page: See it.
duckosm gmns-map [OPTIONS] GMNS_DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
the GMNS mode | driving |
--palette TEXT |
road colours: mono, carto or highsat |
mono |
--source-db PATH |
the core db, for bridges and tunnels in a GMNS file made before links had them | |
-o, --out TEXT |
output HTML | <name>_lanes.html |
gmns-viz¶
Writes an HTML viewer of a GMNS database: lanes, and the meso network when there is one. Hover a line for its attributes. Page: See it.
duckosm gmns-viz [OPTIONS] GMNS_DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
the GMNS mode | driving |
-o, --out TEXT |
output HTML | <name>_viewer.html |
export-gis¶
Writes a GeoPackage, GeoParquet files or shapefiles: edges, nodes and the boundary, edge_id kept. Page:
GeoPackage, GeoParquet and shapefile.
duckosm export-gis [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
modes; repeat for several | every mode in the db |
-f, --format |
gpkg (GeoPackage), geoparquet or shp (shapefile) |
gpkg |
-o, --out TEXT |
.gpkg file, or folder for shapefiles and GeoParquet |
<name>.gpkg / <name>_gis/ / <name>_geoparquet/ |
--boundary / --no-boundary |
include main.boundary as a layer |
on |
--name TEXT |
layer and file name base | the db file name |
gis-debug¶
Reads a GeoPackage or shapefile export back through GDAL and writes an HTML page: a map of every
layer and a check of counts, CRS and edge_ids. Needs geopandas. Page:
Check an export.
duckosm gis-debug [OPTIONS] EXPORT_PATH
| Option | Does | Default |
|---|---|---|
--source-db PATH |
the database to compare against (every edge_id must match) |
|
-o, --out TEXT |
output HTML | <name>_gis_debug.html |
--name TEXT |
name shown on the page | the export file name |
--json |
also print the check as JSON: verdict, summary, each layer |
export-graph¶
Writes a networkx graph file (GraphML or gpickle). Needs networkx. Page: networkx.
duckosm export-graph [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
the mode | driving |
-o, --out TEXT |
output file; the extension picks the format | <name>_<mode>.graphml |
-g, --graph |
node: junctions and roads; edge: the edge-based routing graph |
node |
-f, --format |
graphml or gpickle |
from --out, else graphml |
--weight |
arc weight, time or length; --graph edge only |
time |
--geometry |
edge geometry, wkt, shapely or none; --graph node only; GraphML writes shapely as WKT |
wkt |
--uses TEXT |
more turns for --graph edge: a comma list of bus, private, pedestrian, delivery, the turns into and out of those restricted edges (private_edges); they get an access attribute |
the mode's own turns only |
Experimental and lane-level¶
opendrive¶
Writes an ASAM OpenDRIVE .xodr: roads and lanes. Page: OpenDRIVE.
duckosm opendrive [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
the mode | driving |
--crs TEXT |
projected CRS for the road lines | UTM zone of the data |
--junctions |
also write junctions and turn roads; DB must then be a GMNS database |
|
-o, --out TEXT |
output file | <name>.xodr |
lanelet2¶
Writes a Lanelet2 map (.osm) from a GMNS database: one lanelet per lane. Page:
Lanelet2.
duckosm lanelet2 [OPTIONS] GMNS_DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
the GMNS mode | driving |
-o, --out TEXT |
output file | <name>.lanelet2.osm |
railml¶
Writes a railML 2.4 file of the rail network, read from raw.* (there is no rail mode). Page:
railML.
duckosm railml [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
-o, --out TEXT |
output file | <name>.railml.xml |
lane-graph¶
Builds a lane-level routing graph in a GMNS database: lane-to-lane turns and lane changes, in
lane_<mode>.lane_edges. Page: Lane-level routing.
duckosm lane-graph [OPTIONS] GMNS_DB
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
the GMNS mode | driving |
route-lanes¶
Finds a lane-level route between two lanes and prints the lanes, cost and manoeuvres. Each of
FROM_LANE and TO_LANE is a lane_id, or an edge_id (its lane 1). Uses the table from
lane-graph, or builds the graph in memory without it. Page: Lane-level routing.
duckosm route-lanes [OPTIONS] GMNS_DB FROM_LANE TO_LANE
| Option | Does | Default |
|---|---|---|
-m, --mode TEXT |
the GMNS mode | driving |
-o, --out TEXT |
also write the route as GeoJSON | |
--json |
print the route as JSON: lanes, cost, maneuvers, geometry (WKT) |
Enrich a built database¶
elevation¶
Adds the ground height to every node (nodes.ele) and edge end (edges.z_from, z_to), and a row
in main.elevation_metadata. Running it again overwrites. Needs duckosm[elevation]. Guide:
Add elevation; sources: Elevation sources.
duckosm elevation [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
--dem TEXT |
an elevation file or URL, any format GDAL reads; wins over --source |
|
--source TEXT |
auto, copernicus or eudtm (needs OPENTOPOGRAPHY_API_KEY). auto picks EU-DTM in Europe when the key is set, else Copernicus |
auto |
-m, --mode TEXT |
modes; repeat for several | every mode in the db |
--nodata-fill FLOAT |
height written where the model has no value | 0.0 |
--suffix NAME |
store as a second surface: --suffix dsm writes ele_dsm, z_from_dsm, z_to_dsm |
admin¶
Adds main.admin_boundaries: every OSM administrative boundary in the PBF, with its parent. Replaces
the table if it exists. Needs GDAL's ogr2ogr. Guide:
Add administrative boundaries.
duckosm admin --pbf PBF --db DB [--gpkg GPKG]
| Option | Does | Default |
|---|---|---|
--pbf PBF |
the OSM PBF | required |
--db DB |
the database to add the table to | required |
--gpkg GPKG |
GeoPackage of the boundaries: reused if it exists, else written here (skips the slow ogr2ogr step next time) |
a temporary file |
multimodal¶
Builds mm.edges and mm.transfers, so a route can change mode (walk, drive, walk). Needs walking
and at least one other mode. Page: Routing across modes.
duckosm multimodal [OPTIONS] DB
| Option | Does | Default |
|---|---|---|
--transfer-cost FLOAT |
seconds added at each change of mode | 60.0 |
--schema TEXT |
schema for the two tables | mm |