Create Interactive Maps with Folium

Folium is a Python library that lets you build interactive web maps. It is built on the Leaflet JavaScript library. You can visualize geospatial data and share it as a website[reference:0]. This guide covers everything you need to get started.

What Is Folium?

Folium acts as a bridge between Python and Leaflet. You write Python code. Folium generates the HTML, JavaScript, and CSS needed for a Leaflet map. The result is a clean, interactive map you can open in any browser[reference:1].

You do not need to know JavaScript. You only need basic Python skills. This makes Folium ideal for data scientists and analysts who want to add maps to their reports.

Installation and Setup

Install Folium using pip. Open your terminal and run this command[reference:2]:

pip install folium
  

If you use Conda, run this command instead[reference:3]:

conda install folium -c conda-forge
  

Folium installs its dependencies automatically. These include branca, Jinja2, Numpy, and Requests[reference:4]. You are now ready to create your first map.

Creating Your First Map

The Map class is the foundation of every Folium project. Pass a latitude and longitude pair to set the map center. The following code creates a map centered on Portland, Oregon[reference:5]:

import folium

# Create a base map centered on Portland, Oregon
m = folium.Map(location=(45.5236, -122.6750))

# Display the map in a Jupyter Notebook (just type the variable name)
# m

# Save the map as an HTML file
m.save("index.html")
  

When you run m.save("index.html"), Folium writes a standalone HTML file. Open this file in any browser to see your interactive map[reference:6].

Choosing a Tileset

A tileset controls the look of your base map. OpenStreetMap is the default. Folium also includes CartoDB Positron and Stamen Terrain. Change the tileset with the tiles parameter[reference:7]:

import folium

# Create a map with the CartoDB Positron tileset
m = folium.Map((45.5236, -122.6750), tiles="cartodb positron")
  

You can also use a custom tileset URL. Pass the URL and attribution to the tiles and attr parameters[reference:8]:

import folium

# Create a map with a custom tileset URL
m = folium.Map(
    tiles='https://{s}.tiles.example.com/{z}/{x}/{y}.png',
    attr='My Data Attribution'
)
  

Adding Markers and Popups

Markers point to specific locations on your map. The Marker class places a pin at a given latitude and longitude. Add a popup to show information when clicked[reference:9]:

import folium

m = folium.Map([45.35, -121.6972], zoom_start=12)

# Add a marker with a tooltip and a popup
folium.Marker(
    location=[45.3288, -121.6625],
    tooltip="Click me!",
    popup="Mt. Hood Meadows",
    icon=folium.Icon(icon="cloud"),
).add_to(m)

# Add a second marker with a different color
folium.Marker(
    location=[45.3311, -121.7113],
    tooltip="Click me!",
    popup="Timberline Lodge",
    icon=folium.Icon(color="green"),
).add_to(m)
  

The Icon class customizes the marker's color and symbol. You can choose from hundreds of icons. This helps you distinguish different types of locations on the same map.

Adding Vector Elements

Folium supports vectors such as lines and polygons. The PolyLine class draws a line between coordinates. Use it to show a trail, a road, or a route[reference:10]:

import folium

m = folium.Map(location=[-71.38, -73.9], zoom_start=11)

# Define the trail coordinates
trail_coordinates = [
    (-71.351871840295871, -73.655963711222626),
    (-71.374144382613707, -73.719861619751498),
    (-71.391042575973145, -73.752734250266913),
]

# Add the polyline to the map
folium.PolyLine(trail_coordinates, tooltip="Trail Path").add_to(m)
  

Other vector elements include Polygon for areas and Circle for radius-based zones.

Working with Plugins

Folium includes a plugin system for advanced visualizations. Import plugins from the folium.plugins module[reference:11]:

from folium import plugins
from folium.plugins import HeatMap, MarkerCluster
  

HeatMap Plugin

The HeatMap plugin creates a density visualization. It is perfect for showing concentrations of points. Pass a list of latitude and longitude pairs to create the heatmap[reference:12]:

import folium
from folium.plugins import HeatMap
import random

# Create a base map
m = folium.Map(location=[40.7128, -74.0060], zoom_start=10)

# Generate random points around New York City
heat_data = [[40.7128 + random.uniform(-0.1, 0.1),
              -74.0060 + random.uniform(-0.1, 0.1)]
             for _ in range(200)]

# Add the heatmap to the map
HeatMap(heat_data).add_to(m)
  

The heatmap uses color intensity to show where points are concentrated. Red areas have high density. Blue areas have low density. This is excellent for visualizing crime data, traffic patterns, or disease outbreaks.

MarkerCluster Plugin

When you have thousands of markers, the map becomes cluttered. The MarkerCluster plugin groups nearby markers into clusters. Click a cluster to expand it and see individual markers[reference:13]:

import folium
from folium.plugins import MarkerCluster

m = folium.Map(location=[40.7128, -74.0060], zoom_start=10)

# Create a marker cluster
marker_cluster = MarkerCluster().add_to(m)

# Add many markers to the cluster
for i in range(500):
    folium.Marker(
        location=[40.7128 + (i % 10) * 0.01,
                  -74.0060 + (i % 10) * 0.01],
        popup=f"Point {i}"
    ).add_to(marker_cluster)
  

The cluster shows a number. The number indicates how many markers are inside. This keeps your map fast and readable even with thousands of points.

Creating a Choropleth Map

A choropleth map uses color to represent data values across regions. The Choropleth class binds a pandas DataFrame to a GeoJSON layer. This is ideal for showing population density, election results, or economic indicators[reference:14]:

import folium
import pandas as pd

# Load a GeoJSON file with region boundaries
geo_data = "us-states.json"

# Create a DataFrame with data per state
data = pd.DataFrame({
    "State": ["AL", "AK", "AZ", "AR", "CA"],
    "Value": [10, 20, 30, 40, 50]
})

m = folium.Map(location=[38.0, -95.0], zoom_start=4)

# Add the choropleth layer
folium.Choropleth(
    geo_data=geo_data,
    name="choropleth",
    data=data,
    columns=["State", "Value"],
    key_on="feature.id",
    fill_color="YlOrRd",
    fill_opacity=0.7,
    line_opacity=0.2,
    legend_name="Value per State"
).add_to(m)

# Add a layer control to toggle the choropleth on and off
folium.LayerControl().add_to(m)
  

The fill_color parameter sets the color scheme. Use "YlOrRd" for yellow-to-red or "Blues" for a blue gradient. The key_on parameter matches your data to the GeoJSON features. The LayerControl class adds a toggle so users can turn the choropleth on and off[reference:15].

Displaying and Sharing Your Map

In a Jupyter Notebook, simply type the map variable name to display it. The notebook renders the map inline. You may need to trust the notebook first (File → Trust Notebook)[reference:16].

To share your map, save it as an HTML file with the save method[reference:17]:

# Save the map to an HTML file
m.save("my_interactive_map.html")
  

You can upload this HTML file to any web host. It works as a standalone interactive map. No server-side code is needed.

Common Use Cases

Folium is used across many industries and fields. Here are some practical applications:

Data journalism: Reporters use Folium to show election results, crime statistics, or demographic changes by region.

Urban planning: Planners visualize traffic density, public transit routes, or zoning maps.

Public health: Researchers map disease outbreaks, hospital locations, or vaccination rates.

Real estate: Agents show property locations, school districts, and neighborhood amenities.

Environmental science: Scientists track pollution levels, wildlife habitats, or climate patterns.

Tips for Better Maps

Keep these tips in mind as you build your Folium maps:

Always set a meaningful zoom_start value. A value between 10 and 14 works well for city-level views. Use 4 to 6 for country-level views.

Use LayerControl when you have multiple data layers. This lets users toggle layers on and off. It keeps the map clean and focused.

Test your map in different browsers. Most modern browsers support Leaflet maps without issues. However, some corporate networks block external tile servers.

For large datasets, use MarkerCluster or HeatMap instead of individual markers. These plugins handle thousands of points smoothly.

Conclusion

Folium makes interactive map creation simple and accessible. You can go from a basic map to a complex choropleth in just a few lines of code. The library handles all the JavaScript and HTML generation for you.

Start with the Map class. Add markers and popups. Then explore plugins like HeatMap and MarkerCluster. Finally, bind your data to GeoJSON layers with Choropleth. Each step builds on the previous one.

Whether you are a data scientist, journalist, or developer, Folium is a powerful tool for geospatial visualization. Install it today and start mapping your data.