geolibre

GeoLibre in Jupyter: the full GeoLibre GIS app as an anywidget, with a leafmap-style Python API.

The widget embeds the complete GeoLibre app (menus, panels, processing tools) inside a notebook cell. State syncs both ways through a single .geolibre.json project, so data you add from Python appears in the UI, and edits you make in the UI are readable back from Python.

Install

pip install geolibre

Or with conda from conda-forge:

conda install -c conda-forge geolibre

Quickstart

from geolibre import Map

m = Map(center=(-100, 40), zoom=4)
m.add_geojson("https://example.com/data.geojson", name="Data")
m

Add more data and drive the view:

m.add_tile_layer(
    "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
    name="OpenStreetMap",
    attribution="(c) OpenStreetMap contributors",
)
m.add_cog("https://example.com/dem.tif", name="DEM", colormap="terrain")
m.add_basemap("dark")
m.set_center(-120, 47, zoom=8)

Google Earth Engine layers are optional and need pip install earthengine-api plus credentials (ee.Authenticate() once, then a Google Cloud project):

import ee

ee.Authenticate()  # once per machine
ee.Initialize(project="your-google-cloud-project")
m.add_ee_layer(ee.Image("USGS/SRTMGL1_003"), {"min": 0, "max": 3000}, name="SRTM")

Round-trip the project:

m.save_project("my-map.geolibre.json")

m2 = Map()
m2.load_project("my-map.geolibre.json")

# Read state edited in the UI (e.g. after panning/zooming):
m.to_project()["mapView"]["center"]

API

Layer handles provide the same operations in an object-oriented form:

m.add_geojson("https://example.com/roads.geojson", name="Roads")

roads = m.find_layer("Roads")  # None when no layer has that name
roads.opacity = 0.6
roads.set_style(lineColor="#e63946", lineWidth=3)
roads.move(0)

print(roads.properties())      # sampled values for every property
print(roads.column("highway")) # one value per feature
roads_copy = roads.duplicate(name="Roads (proposed)")

Run a Whitebox tool against a map layer (the map must be displayed first):

dem = m.get_layer(m.add_raster("https://example.com/dem.tif", name="DEM"))
result = m.run_whitebox_tool("slope", {"input": dem, "units": "degrees"})
slope = m.get_layer(result["resultLayerIds"][0])

For headless authoring and scripts that do not need a widget, commonly used project utilities are available directly from the top-level package:

from geolibre import (
    basemap_catalog,
    builtin_legend_names,
    color_ramp_names,
    describe_project,
    load_project,
    save_project,
)

project = load_project("my-map.geolibre.json")
print(describe_project(project))
save_project("copy.geolibre.json", project)

These are the lossless file primitives: unlike Map.save_project, the top-level save_project writes the project verbatim, credentials included, so that editing a project in place cannot strip your own API keys out of it. Pass a project through geolibre.project.redact_credentials first if the file is going anywhere untrusted, or use Map.save_project, which redacts by default.

Notes

• marimo can render the anywidget, but its browser may not be able to reach GeoLibre's random localhost port. If the iframe reports 127.0.0.1 refused to connect, select the hosted app before displaying the map:

  from geolibre import Map
  
  m = Map(center=(-100, 40), zoom=4)
  m._app_url = "https://web.geolibre.app/"
  m.add_basemap("dark")
  m.add_vector(
      "https://data.source.coop/giswqs/opengeos/world_cities.geojson",
      name="World cities",
  )
  m
  

  Set _app_url before returning m from the cell. With the hosted app, use hosted URLs for rasters and other browser-loaded sources; it cannot access files served from the kernel's temporary localhost server. Local GeoJSON, CSV, and vector files that are read in Python and inlined still work. The example uses add_vector() so the browser, rather than Python, fetches the remote GeoJSON URL.

  Privacy: The widget sends its synchronized project, including any inlined local data, to the origin in _app_url through window.postMessage. Use only a trusted app URL, or host the GeoLibre app yourself, when working with sensitive data.

• The bundled app is served from a localhost HTTP server, so the interactive widget works in local Jupyter and VS Code directly. Google Colab routes through its built-in port proxy automatically. On JupyterHub (including managed/shared hubs) the front-end tries two same-origin routes and uses whichever is live, so a host needs only one of them: the Jupyter Server extension bundled with geolibre at {base_url}geolibre/app/ (enabled automatically on pip install geolibre, but registered only after the Jupyter server restarts), and jupyter-server-proxy at {base_url}proxy/{port}/ (works in the running server with no restart where it is installed). On other remote servers (Binder, remote JupyterLab), pass Map(server_proxy=True) to use that same remote path; Map(server_proxy=False) forces the direct path.

• add_ee_layer needs the Earth Engine Python API, which is not a dependency of this package: pip install earthengine-api. Authenticate once with ee.Authenticate() and initialize with ee.Initialize(project=...) before adding a layer. The generated tile URL is tied to an Earth Engine map id that expires, so a saved project may need the layer regenerated later.

• Optional extras: pip install "geolibre[all]" adds GeoPandas/Shapely support for add_geojson(geodataframe) and for reading local vector files (add_vector/add_geoparquet/add_flatgeobuf/add_shp/add_kml/add_gpkg), plus xarray/rioxarray/rasterio/rio-tiler support for in-memory rasters. Colab uses rio-tiler to serve these as PNG XYZ tiles because its proxy does not preserve browser COG byte ranges. [vector] and [raster] install just one half each -- [all] pulls in rasterio (and GDAL). The kernel reads local vectors and inlines them as GeoJSON; remote URLs for those formats stream through the in-browser vector control and need no extras.

• add_geojson inlines file/URL data into the project (up to 50 MB), so a large dataset is held in memory and re-synced on every project update. For very large layers, prefer a tile or COG source (add_tile_layer/add_cog) the app fetches directly.

MCP server

The package also ships a headless MCP server that authors .geolibre.json projects from an AI client:

pip install "geolibre[mcp]"
geolibre-mcp --root ~/maps

It confines every read and write to the roots you pass (--root, repeatable, or GEOLIBRE_MCP_ROOTS) and builds projects through the same builders this package uses, so anything it writes opens in the widget unchanged. See docs/mcp.md for the tool list and client configuration.