Library / SDK
python-visualization/folium avatar
python-visualization/folium

folium: Python Data, and a wheel full of JavaScript

Python Data. Leaflet.js Maps.

7,420 stars2,270 forksPythonNOASSERTION

At a glance

What is it?
folium lets you manipulate data in Python and hand it to Leaflet.js, and the interesting part of the repository is how little of it is pure Python. The wheel ships the JavaScript and the templates it renders, the runtime dependencies are five, and the project file marks the version and most metadata as dynamic. The performance and attribution problems are deliberately not solved in the package.
Who is it for?
Adopt it when you already do your data work in Python and want an interactive web map without a JavaScript build step. Do not adopt it expecting a static export, a tile server or a rendering layer for very large feature collections, since those are separate projects.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • python-visualization/folium7,420 ★ · +17
Star history
Repository2026-09-222026-11-15
python-visualization/folium7.4k7.4k

17 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The wheel ships Leaflet's JavaScript, which is why Jinja is a dependency

A folium map is an HTML document, and the document is assembled from templates and shipped JavaScript that live inside the package. The packaging file lists what goes in: loose JavaScript at the package root, a plugins directory with its own scripts, stylesheets, templates and page fragments, a templates directory holding HTML, JavaScript and text templates, and a marker file for type checkers. It also walks the tile templates directory and adds everything found there, which is how a library ends up carrying a catalogue of basemap providers inside the wheel. The runtime dependency list is short and explains the design:

text
branca>=0.6.0
jinja2>=2.9
numpy
requests
xyzservices

Jinja is there because the map is rendered, the tile index is there because tiles have to be looked up, and the rest is the usual numeric and HTTP surface. The consequence is that folium is not a pure Python library you can vendor as source and expect to work; the front end travels with it.

The runtime dependencies are parsed from the file the variable calls tests

There is a small oddity in the packaging file worth naming, because it explains how the project manages dependencies. The script opens requirements.txt, reads it into a variable named for test requirements, and then uses that same list as the install requirements:

python
with open("requirements.txt") as f:
    tests_require = f.readlines()
install_requires = [t.strip() for t in tests_require]

So the file at the repository root is the runtime dependency set, whatever the local variable calls it, and the development dependencies live in a separate file beside it. The content is the five packages above, with floor versions on the two libraries that are easy to break and nothing at all on the three that are already in almost every environment. The consequence is procedural rather than dramatic. If you add a runtime dependency, you add it to that one file, and if you are reading a folium install to work out what it pulls in, that file is the answer rather than the project metadata.

Every piece of package identity lives in setup.py, not in the project file

The project file is mostly a list of things it does not know. The build system asks for setuptools, a version helper and the wheel tool, then declares the name and the Python floor, and everything else is marked dynamic:

toml
dynamic = [
    "version",
    "description",
    "readme",
    "license",
    "authors",
    "keywords",
    "classifiers",
    "dependencies",
    "optional-dependencies",
]
requires-python = ">=3.9"

The concrete values live in the older setup script, which names the author, the licence, the keywords, the long description read straight from the README in reStructuredText form, and a classifier block listing Python 3.9 through 3.13 plus the GIS and visualisation topics. So if you are automating against this repository, the project file alone will not tell you the version, the dependencies or the licence. That is a transitional layout rather than a design choice, and it is worth knowing before you script a check against it.

Three lint groups and an 85 percent docstring threshold

The tooling configuration says what this project considers its risks. The linter selects three rule groups and nothing else: flakes, import sorting, and pyupgrade rules, targeting the same Python version as the floor, with a line length of 120. That is a deliberately narrow surface, which fits a library whose output is text and whose main failure mode is an unused import. Static typing is configured to ignore missing imports. Then there is a documentation gate: a docstring coverage tool with a failure threshold of 85 percent, ignoring initialisation methods but not magic methods, semi-private or private members, and excluding the packaging script, the docs and the tests. So public methods are expected to explain themselves, and the check that enforces it is part of the ordinary workflow rather than a courtesy.

Rendering speed and attribution are plugin problems, not package problems

The README lists what folium itself does not do, by pointing at other projects. For large feature collections, a plugin provides fast WebGL rendering instead of the default path. For attribution, another plugin puts credits in the corner as an expandable image or message. For a geocoder that offers a fixed list of suggestions at creation time rather than querying, there is a plugin. And for tiles, one plugin zooms and stretches past the maximum and minimum the tile provider declares. Packages sit alongside those: a repository of raster basemap tile sets, a wrapper for running folium inside a Streamlit application, and a tool for viewing finite element simulations on geographic maps. The consequence is practical. If your map has ten points, folium alone is enough, and if it has fifty thousand you are choosing a rendering strategy from a list of separate projects with their own release cycles.

Version 1.0.0 has been sitting in pre-release since July 2026

The release list is three entries and the newest one is not the stable one. Version 1.0.0-pre.1 was published 2026-07-26, after 0.20.0 from 2025-06-16 and 0.19.7 from 2025-06-03. So the major version has been in a pre-release for over three months, with 0.20.0 as the line to pin for production. The changelog guidance matches that shape: release notes from 0.16.0 onward live on the releases page, and anything older is in a plain text file at the repository root. The repository is not archived and the last push on main is dated 2026-11-01. For a library this widely used, the version to choose is straightforward, and the thing to avoid is depending on the pre-release in a deployment you cannot rebuild.

The examples directory is the documentation, and Binder will run it for you

The README is short because the documentation lives elsewhere: the reference is on a hosted documentation site, and the repository carries an examples directory of notebooks named after the feature each one demonstrates. There are examples for choropleths with natural breaks optimisation, click events, colour maps, custom map panes, feature groups, image overlays, GeoJSON with and without titles, popups and tooltips, heat maps including one with a time slider, marker clustering, minimum and maximum limits, a mini map, and one that uses the GeoPandas interface directly. A Binder badge points at that examples directory on a specific branch, so you can open a notebook in a browser without installing anything. That is also the fastest way to answer most questions about this library, since the reference tells you a method exists and the notebook shows you what it renders.

Editorial conclusion

Adopt it when you already do your data work in Python and want an interactive web map without a JavaScript build step. Do not adopt it expecting a static export, a tile server or a rendering layer for very large feature collections, since those are separate projects. Before you upgrade, note that 1.0.0 is still a pre-release and the current stable line is 0.20.0.

Frequently asked questions

What does folium do in Python?

It lets you manipulate your data in Python and then visualise it in a map built on the Leaflet.js library. The package ships the JavaScript and templates it renders, which is why its runtime dependencies include a template engine alongside numpy, requests and the raster tile provider index. The map is an HTML document you can save, serve or embed.

how to install folium in python

Two commands: pip install folium, or conda install -c conda-forge folium. Python 3.9 or newer is required, and the classifiers list 3.9 through 3.13. The reference documentation is hosted at the project's documentation site, and the examples directory can be launched in a browser through the project's Binder link if you would rather not install anything.

What is folium used for?

Interactive web maps built from Python data: choropleths, markers and marker clusters, heat maps, GeoJSON and image overlays, click events, and custom map panes. For rendering speed on large feature collections, for attribution in a corner, for a geocoder with preset suggestions, or for tiles that stretch past the provider's declared limits, the project points at separate plugins and packages rather than folding them into the package.

Official sources

  1. Issues
  2. Project website
  3. python-visualization/folium on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/python-visualization-folium.svg)](https://hysenlabs.com/projects/python-visualization-folium)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/python-visualization-folium.svg)](https://hysenlabs.com/projects/python-visualization-folium)

Was this useful?