# leafmap: interactive geospatial mapping in a Jupyter environment

> leafmap wraps folium and ipyleaflet behind a one-line API and a no-code GUI, with WhiteboxTools as the analysis backend. It is aimed at people who want a map on screen before they want a GIS stack.

**opengeos/leafmap** — A Python package for interactive mapping and geospatial analysis with minimal coding in a Jupyter environment

- Repository: https://github.com/opengeos/leafmap
- Website: https://leafmap.org
- Stars: 3,781 · Forks: 473
- Language: Python
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/opengeos-leafmap

## The gap leafmap fills between geopandas and a browser map

The README is direct about the problem. geopandas handles vector analysis, xarray handles raster analysis, and pyviz.org lists plenty of plotting options, but getting data from a file onto an interactive map is still awkward, particularly for people with limited coding skills. The README also names a second issue: many plotting tools lack bi-directional communication between the browser and the Python backend, so the map is a picture rather than a control surface.

leafmap is a spin-off of geemap, which was built for Google Earth Engine. The stated motivation for the split is that not everyone in the geospatial community has access to that cloud platform. So the audience is non-GEE users who still want the geemap experience: a notebook, a map, a layer list, and a toolbox. The README says it is designed for anyone who wants to analyze and visualize geospatial data interactively in Jupyter, and explicitly calls it accessible for novice users. Advanced users get the same API plus the option to build web apps.

That positioning matters when you decide whether to adopt it. leafmap is not trying to replace geopandas or xarray. It is the display and interaction layer that sits on top of them, plus a GUI for people who would rather click than type.

## How leafmap is put together: folium, ipyleaflet and WhiteboxTools

The README lists the dependencies that define the architecture. folium and ipyleaflet create the interactive maps. ipywidgets builds the graphical interface. WhiteboxTools, through whiteboxgui, is the analysis backend, and the README states that the WhiteboxTools library contains more than 500 tools covering GIS analysis, geomorphometric analysis, hydrological analysis, LiDAR data analysis, mathematical and statistical analysis, and stream network analysis.

The split between folium and ipyleaflet is the part worth understanding before you install. folium renders to HTML through Leaflet, which means the output is a static document you can save and share. ipyleaflet is a Jupyter widget, so the browser and the Python kernel talk to each other in both directions. That bidirectional channel is what the README credits for the interactive toolset: you can load vector and raster data onto the map without coding, and run WhiteboxTools from the interface. A folium-backed map cannot do that, because there is no live kernel behind it.

The practical consequence is that the two backends are not interchangeable. Anything that depends on widget callbacks, the layer manager, or the analysis GUI requires the ipyleaflet path. If you only need a shareable HTML map, the folium path is lighter and does not need a running kernel.

The optional dependency groups in pyproject.toml make the same point from the packaging side. There are separate extras for backends (bokeh, keplergl, maplibre, pydeck, plotly), raster (localtileserver, rioxarray, titiler, and others), vector (geopandas, osmnx, pmtiles, lonboard, mapclassify), lidar, sql, apps, usgs, pmtiles, maplibre and ai. leafmap installs a core set and expects you to name the extras your work actually needs.

## Installing leafmap and drawing a first map

The README points at PyPI and conda-forge as the two distribution channels, and the repository ships a conda environment.yml alongside requirements.txt. The simplest install is pip:

```bash
pip install leafmap
```

After that, a first map is one import and one call. The README's central claim is that datasets load with one line of code, and the package's own key-features notebook is the reference for what that looks like in practice:

```python
import leafmap

m = leafmap.Map(center=[40, -100], zoom=4)
m
```

The Map object is the entry point for everything else in the interactive workflow: adding vector and raster layers, opening the layer manager, and launching the toolbox. In a notebook, the returned object renders as a live widget rather than a saved image.

If you prefer conda, the README links the conda-forge feedstock, and the repository's environment.yml is the file that describes the full environment the project itself uses:

```bash
conda install -c conda-forge leafmap
```

For a container, the repository includes a Dockerfile that starts from quay.io/jupyter/base-notebook:latest, installs leafmap plus gdal, proj, geos, fiona, rasterio, rioxarray and voila through mamba, and sets PROJ_LIB, GDAL_DATA and LOCALTILESERVER_CLIENT_PREFIX. It also raises the Tornado websocket message size to 100 MB, which tells you something about how much data the widget channel can carry. Nothing in the README documents a rollback procedure for a bad upgrade, so pin your version if that matters to you.

## Where leafmap stops being the right tool

The dependency split is also the main limitation. The interactive toolset, the GUI, and the WhiteboxTools integration all ride on ipywidgets and ipyleaflet. That means the environment has to render Jupyter widgets, and the README's own list of supported environments (Google Colab, Jupyter Notebook, JupyterLab, marimo) is a hint that a bare Python script or a headless CI job is not the target. If your pipeline runs in a scheduler with no kernel and no browser, the parts of leafmap you would want are the parts that do not work there.

Second, the analysis backend is an external binary. WhiteboxTools is not a pure-Python dependency, and the README treats it as the analytical engine behind the no-code GUI. If that binary is unavailable for your platform or your execution environment, the GUI analysis features are unavailable too, even though the mapping layer still works.

Third, the optional extras mean the install is a decision, not a single command. The vector extra pulls geopandas, osmnx, pmtiles, lonboard and mapclassify; the raster extra pulls localtileserver, rioxarray, titiler and uvicorn. Installing everything to be safe produces a large environment, and the README does not promise that every combination of extras has been exercised together.

Finally, leafmap is a visualization and interaction layer, not an analysis library in the geopandas sense. If your task is a batch overlay of two large vector files with no map involved, geopandas alone is the smaller dependency. leafmap earns its place when someone needs to look at the data and adjust it while looking.

## leafmap vs folium: the difference is the kernel

folium is the obvious comparison because leafmap uses it. The difference is architectural. folium produces a Leaflet map as HTML: you build it, render it, and the result is a document. There is no Python process behind the page in the browser, so a click on the map cannot call back into your notebook.

leafmap's ipyleaflet path keeps that channel open. The README's statement of need says many tools lack bi-directional communication between frontend and backend and that this limits interactivity, and ipyleaflet is the mechanism leafmap uses to avoid that. In practice this is why the layer manager, the file chooser, and the WhiteboxTools GUI exist at all: they are widgets driving a live kernel.

The trade-off runs the other way too. A folium HTML file can be emailed, committed, or served as a static asset. An ipyleaflet widget needs a running kernel and the right frontend extensions, which is why the README's environment list is short and specific. If your deliverable is a map someone else opens without installing anything, folium is the safer choice and leafmap's folium backend is a reasonable middle ground. If your deliverable is an exploration session, the widget path is the whole point.

## Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-21. The release history shows v0.63.1 on 2026-08-02, v0.63.0 on 2026-07-04, and v0.62.0 on 2026-04-30, so the cadence over that window is roughly monthly with a patch in between. The version in pyproject.toml is 0.63.1, and the project declares requires-python >= 3.9 with classifiers for 3.9 through 3.13.

The upgrade cost is dominated by the extras rather than by leafmap itself. A version bump can pull new pins in the raster or vector groups, and because those groups include compiled geospatial libraries (gdal, proj, geos, rasterio, fiona appear in the Dockerfile), the environment is where breakage usually shows up rather than in leafmap's own API. The Dockerfile's sqlite symlink workaround is a small illustration of the kind of environment-specific fix a geospatial stack sometimes needs.

On licensing: leafmap is MIT, and pyproject.toml carries the MIT license classifier. That is permissive, but leafmap depends on and optionally installs a large set of third-party packages, and WhiteboxTools is a separate project with its own terms. If you are redistributing a bundled environment, the licences that matter are the ones attached to those dependencies, not leafmap's. That is a fact about the dependency graph, not legal advice, and you should check the terms of each component you ship.

## Conclusion

Adopt leafmap if your work lives in a notebook and you need a map on screen in the first five minutes, with WhiteboxTools available when the analysis gets heavier. Skip it if you need a production web map or a pure static-plotting library; leafmap's value is the interactive notebook session, not a deployed endpoint. Before committing, verify that your environment can render the ipyleaflet widget (a plain Jupyter kernel is not enough if the widget extension is missing), check which optional extras your raster or vector workflows need, and confirm the WhiteboxTools binary is available in your platform, since the GUI analysis depends on it.

## FAQ

### How do I install leafmap?

The README points to PyPI and conda-forge, so pip install leafmap or conda install -c conda-forge leafmap both work. The repository also ships a Dockerfile based on the Jupyter base notebook image if you prefer a container.

### What is leafmap?

It is a Python package for interactive mapping and geospatial analysis with minimal coding in a Jupyter environment. It is a spin-off of geemap, built on folium and ipyleaflet for maps and WhiteboxTools for analysis.

### Is leafmap free?

Yes. The README describes it as a free and open-source Python package, and the repository is licensed under MIT.

### What is the difference between geemap and leafmap?

geemap was designed specifically to work with Google Earth Engine, and leafmap is a spin-off created because not everyone in the geospatial community has access to that cloud platform. leafmap targets non-GEE users who still want interactive mapping in a notebook.

### What can I use instead of leafmap?

The README names ipyleaflet and folium directly, along with hvPlot, bokeh and plotly as general-purpose plotting tools that also handle geospatial data. leafmap sits on top of folium and ipyleaflet rather than replacing them.

## Sources

- [License: MIT](https://github.com/opengeos/leafmap/blob/master/LICENSE)
- [opengeos/leafmap on GitHub](https://github.com/opengeos/leafmap)
- [Project website](https://leafmap.org)
- [README](https://github.com/opengeos/leafmap/blob/master/README.md)
- [Releases](https://github.com/opengeos/leafmap/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/opengeos-leafmap