Streamlit-Folium

0.27.1 · active · verified Thu Apr 16

Streamlit-Folium seamlessly integrates the Folium mapping library into Streamlit applications, allowing users to render interactive geospatial visualizations. It provides both a bi-directional component, `st_folium()`, for enhanced user interaction and a static renderer, `folium_static()`. The library is actively maintained, with its current version 0.27.1 released on March 26, 2026, indicating a consistent release cadence.

Common errors

```
ModuleNotFoundError: No module named 'folium'
```
cause Either `folium` or `streamlit-folium` (which depends on `folium`) is not installed in the environment where the Streamlit app is running, or there's a version conflict.

fix Run `pip install folium streamlit-folium` to ensure both libraries are present and compatible. Verify your `requirements.txt` if deploying.
```
StreamlitAPIException: folium_static() is not a valid Streamlit command.
```
cause You are attempting to call `folium_static` directly on a Streamlit layout element (e.g., `col.folium_static(m)`), which is not how custom components interact with layout objects.

fix Wrap the component call in a `with` block for the layout element: `with col: folium_static(m)` or `with col: st_folium(m)`.
```
Randomly get "Your app is having trouble loading the streamlit_folium.st_folium component." Had to reboot.
```
cause Streamlit's frontend assets for `streamlit-folium` are failing to load, often due to an incomplete installation, caching issues, or network/proxy restrictions.

fix Try `pip install --upgrade streamlit-folium` to ensure all assets are correctly installed. Clear your browser cache or try a different browser. If deploying, check network configurations.
```
MarkerCluster not working properly in Streamlit 1.34 onwards
```
cause Compatibility issues between `folium.plugins.MarkerCluster` and newer Streamlit versions or `streamlit-folium`.

fix Check the `streamlit-folium` GitHub issues for specific fixes or workarounds. This often requires updating `streamlit-folium` or `folium` to a version with a patch, or adjusting how MarkerCluster is initialized.

Warnings

gotcha Using `folium_static()` within Streamlit columns (e.g., `col.folium_static(m)`) can raise a `StreamlitAPIException`. Components directly exposed by Streamlit (`st.`) cannot be called on column objects in this manner.
Fix: Use a `with` block: `with col: folium_static(m)`.
breaking The `st_folium()` component is generally preferred over `folium_static()` for modern Streamlit apps due to its bi-directional communication, allowing map interactions (clicks, zooms) to be passed back to Python. `folium_static()` only renders a static HTML representation.
Fix: Migrate from `folium_static(m)` to `st_folium(m)` to leverage interactive features and pass data back to Streamlit.
gotcha Deployment issues often stem from frontend assets not loading correctly for `streamlit-folium` components, leading to errors like 'Your app is having trouble loading the streamlit_folium.st_folium component.'. This can be due to improper installation or network/proxy configurations.
Fix: Ensure `streamlit-folium` (and `folium`) are correctly installed in your deployment environment. Restart the app/terminal. Check for restrictive firewalls or proxy settings, especially in corporate networks.
deprecated Python 3.10 support was dropped in recent versions (e.g., v0.27.0).
Fix: Ensure your project uses Python 3.11 or newer to avoid compatibility issues.

Install

pip install streamlit-folium Install latest version

Imports

st_folium
```
from streamlit_folium import st_folium
```
The primary bi-directional component for interactive maps.
folium_static
wrong:
```
import streamlit_folium.folium_static
```
correct:
```
from streamlit_folium import folium_static
```
This is a convenience function for static rendering, less interactive than `st_folium`.

Quickstart

This example initializes a Folium map centered on the Liberty Bell, adds a marker, and then renders it in a Streamlit application using the `st_folium` component, which enables bi-directional interaction. The `st_data` variable captures interaction events from the map.

import streamlit as st
import folium
from streamlit_folium import st_folium

st.set_page_config(layout="wide")

m = folium.Map(location=[39.949610, -75.150282], zoom_start=16)

folium.Marker(
    [39.949610, -75.150282],
    popup="Liberty Bell",
    tooltip="Liberty Bell"
).add_to(m)

st_data = st_folium(m, width=725)

view raw JSON →