Folium: Python Data, Leaflet.js Maps

What Folium solves for Python users

The gap Folium fills is between a DataFrame and a web map. Leaflet.js is a JavaScript library, and using it directly means writing JavaScript, wiring up tile layers, and managing the HTML page yourself. Folium takes the other side of that: you manipulate data in Python, and Folium emits the Leaflet map for you. The README states this plainly, describing a project that "builds on the data wrangling strengths of the Python ecosystem and the mapping strengths of the Leaflet.js library."

The audience follows from that split. If your data already lives in pandas, GeoPandas or a list of coordinates, and your output target is a notebook cell, an HTML file or a dashboard component, Folium is aimed at you. The repository's examples directory is a catalogue of those cases: Choropleth with Jenks natural breaks optimization, Heatmap, MarkerCluster, GeoJSON_and_choropleth, Geopandas_and_geo_interface. Each is a notebook, which tells you the expected working environment is interactive analysis rather than a batch pipeline.

It is not a GIS. There is no projection engine, no spatial join, no raster algebra. Folium draws what you hand it and delegates the geometry work to whatever produced your coordinates.

How Folium produces a map: Python objects into HTML

The mechanism is code generation. A folium.Map object accumulates layers, and when you display it or save it, Folium renders a Jinja2 template into an HTML document containing Leaflet JavaScript. The dependencies in requirements.txt show the pieces: branca, jinja2, numpy, requests, xyzservices. Jinja2 does the templating, branca supplies the colormaps and the element base classes, and xyzservices provides the raster basemap tilesets.

The packaging confirms that the JavaScript ships inside the Python package rather than being fetched at install time. setup.py declares package_data covering "*.js", "plugins/*.js", "plugins/*.html", "plugins/*.css", "plugins/*.tpl", "templates/*.html", "templates/*.js", "templates/*.txt", plus a walk over templates/tiles. The templates/tiles directory is populated by walk_subpkg, which means the default tile definitions are bundled files, not something resolved from the network during build.

So the data flow runs one way. Python objects become a template context, the context becomes an HTML string, and the browser executes Leaflet against that string. Nothing in this chain keeps a connection back to your Python process. That single fact explains most of the project's strengths and most of its limits.

Installing Folium and drawing a first map

The README gives two installation routes, pip and conda-forge. Either is a single command, and neither requires a JavaScript toolchain.

pip install folium

The alternative for conda users is the conda-forge channel:

conda install -c conda-forge folium

That is the whole documented setup. The README does not include a first-map snippet, so the smallest working example has to come from the repository's examples directory instead. Those notebooks are listed in the README through a Binder badge pointing at mybinder.org with filepath=examples, which means you can open them without installing anything locally. The names tell you what each covers: CustomIcon.ipynb, MarkerCluster.ipynb, Heatmap.ipynb, GeoJSON_and_choropleth.ipynb, ClickEvents.ipynb, Colormaps.ipynb.

What you should expect from any of them is the same shape: a map object is created first, layers are added to it, and the result is displayed in the notebook or written out as HTML. Because the examples are notebooks rather than scripts, the intended first run is interactive, not a command-line invocation.

Where Folium stops being the right tool

The output is a static document. Once Folium has written the HTML, the Python side is finished. If your data changes every thirty seconds and the map must reflect that, Folium gives you no channel to push the update; you would have to regenerate and reload the page. This is the direct consequence of the templating design described above, and it is the boundary that matters most when choosing the tool.

Scale is the second constraint. Every feature you add becomes JavaScript in the page. The README's own plugin list acknowledges this: folium-glify-layer is described as providing "fast webgl rendering for large GeoJSON FeatureCollections." If a plugin exists specifically to make large GeoJSON collections render fast, the default path has a practical ceiling on feature count. The HeatMapWithTime and MarkerCluster examples are the same kind of answer for dense point data.

Third, Folium does not host anything. There is no server component in the repository. Deployment means serving a static HTML file and whatever tiles it references, and the README documents no hosting story beyond that. If you need a map endpoint that other services query, Folium is the wrong layer.

Folium against GeoPandas plotting and raw Leaflet

The nearest alternative in a Python workflow is GeoPandas' own plotting, which renders through matplotlib. The difference is not cosmetic. GeoPandas draws a static image in the Python process; Folium emits interactive HTML that runs in a browser. Panning, zooming, tooltips and popups exist in Folium because Leaflet provides them, and they do not exist in a matplotlib figure at all. The trade-off runs the other way too: a matplotlib figure can be embedded in a PDF or a printed report, while a Folium map cannot.

The other alternative is writing Leaflet directly. That gives you full control over the JavaScript and avoids the templating layer entirely, at the cost of doing in JavaScript what Folium does from Python. Folium's own plugin ecosystem sits between the two: folium-vectortilelayer, folium-geocoder-own-locations and Folium.ControlCredits-Plugin each extend the generated map rather than replacing it. If your need maps cleanly onto an existing plugin, staying in Folium is cheaper than dropping to Leaflet; if it does not, you are fighting the template.

Release status, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-21. The most recent release is v1.0.0-pre.1, dated 2026-07-26, which is a pre-release rather than a stable tag. The last stable release listed is v0.20.0 from 2025-06-16, preceded by v0.19.7 on 2025-06-03. Anyone pinning a version for production should be aware that the 1.0 line has not yet reached a stable release, and that the pre-release exists alongside the 0.x series.

Upgrade cost is bounded by the dependency floor. pyproject.toml sets requires-python to ">=3.9", and the classifiers in setup.py list Python 3.9 through 3.13, so the package tracks current interpreters. The runtime dependencies are branca>=0.6.0, jinja2>=2.9, numpy, requests and xyzservices. branca is the one to watch on upgrades, since it supplies the colormap and element classes that Folium's API is built on; a major branca change would ripple through Folium's own interface.

On licensing: setup.py declares license="MIT" and the classifiers include "License :: OSI Approved :: MIT License", while the repository metadata reports the licence as NOASSERTION. The file in the repository root is LICENSE.txt. If the licence terms matter to your organisation, read that file rather than relying on either machine-readable field, and treat the discrepancy between the two as something to resolve internally.

Contributor tooling is enforced rather than advisory. pyproject.toml configures interrogate with fail-under = 85 and ruff with a 120-character line length targeting py39. Those settings say something about the maintenance posture: docstring coverage is a build gate.

Editorial conclusion

Folium fits analysts and notebook users who already have data in pandas or GeoPandas and want an interactive map without writing JavaScript. It does not fit anyone who needs server-side tile rendering, live-updating maps, or a hosted map endpoint, because the output is a self-contained HTML document. Before adopting it, check that your deployment can serve the Leaflet assets and the basemap tiles the map requests, and confirm which release you are pinning: v1.0.0-pre.1 is a pre-release, while v0.20.0 is the most recent stable tag.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. python-visualization/folium on GitHub
4. README
5. Releases