Folium — Interactive Map Visualization with Python and Leaflet

Introduction

Folium is a Python library that bridges the gap between Python data analysis and interactive web maps. It generates Leaflet.js maps as standalone HTML files, allowing you to overlay markers, choropleth layers, heatmaps, and GeoJSON data using a simple Python API without writing any JavaScript.

What Folium Does

• Creates interactive Leaflet.js maps from Python with markers, popups, and tooltips
• Renders choropleth maps by binding pandas DataFrames to GeoJSON boundaries
• Supports heatmaps, clustered markers, and time-based animations
• Outputs self-contained HTML files or renders inline in Jupyter notebooks
• Provides multiple tile layers (OpenStreetMap, CartoDB, Stamen, and custom)

Architecture Overview

Folium wraps Leaflet.js and its plugin ecosystem in Python classes. Each map element (markers, layers, controls) is represented as a Python object that generates the corresponding JavaScript when rendered. The Map object acts as the root container. Elements are added via .add_to(), building a tree that serializes to an HTML document embedding Leaflet and its plugins. Jinja2 templates handle the HTML generation.

Self-Hosting & Configuration

• Install via pip install folium or conda install -c conda-forge folium
• Set the base tile layer with the tiles parameter (e.g., "CartoDB positron", "OpenStreetMap")
• Adjust initial view with location (lat/lon), zoom_start, and max_zoom
• Add custom tile servers by providing a URL template and attribution string
• Save maps with m.save("output.html") or display in Jupyter with m in a cell

Key Features

• Zero JavaScript required to build interactive web maps from Python
• Rich plugin ecosystem: MarkerCluster, HeatMap, TimestampedGeoJson, MiniMap, and more
• Native Jupyter notebook integration with inline rendering
• Choropleth maps with pandas/GeoJSON binding and automatic color scaling
• Lightweight output as self-contained HTML files

Comparison with Similar Tools

• Plotly — General interactive charting with map support; Folium is map-specialized with richer Leaflet features
• Kepler.gl — GPU-accelerated large-scale geodata; Folium is lighter and simpler for standard maps
• ipyleaflet — Jupyter widget with bidirectional Python-JS communication; Folium produces static HTML
• GeoPandas.plot() — Static matplotlib maps; Folium provides interactive, zoomable web maps
• deck.gl — WebGL layer rendering for big data; Folium targets simplicity over scale

FAQ

Q: Can Folium handle large datasets? A: For thousands of markers, use MarkerCluster or FastMarkerCluster. For very large datasets, consider pre-processing or switching to Kepler.gl.

Q: Does Folium work outside Jupyter notebooks? A: Yes. Maps can be saved as standalone HTML files and opened in any web browser.

Q: Can I use custom map tiles? A: Yes. Pass a custom tile URL template via the tiles parameter along with an attr attribution string.

Q: What coordinate system does Folium use? A: Folium uses WGS84 (EPSG:4326) coordinates — standard latitude/longitude.

Sources

• https://github.com/python-visualization/folium
• https://python-visualization.github.io/folium/