Install & Compatibility
Where this runs
tested against v0.3.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 64.2s
py 3.11
✕ build_error
✓ 62.6s
py 3.12
✕ build_error
✓ 61.3s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 69.75s
778MB installed
● package 778MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
KeplerGl
✓ from keplergl import KeplerGl
This quickstart demonstrates how to initialize a Kepler.gl map and add a Pandas DataFrame. The map can then be displayed in a Jupyter environment or saved as an interactive HTML file. A Mapbox API key is often required for base map functionality.
import pandas as pd
from keplergl import KeplerGl
import os
# Create a sample DataFrame
data = {
'lat': [34.0522, 36.1699, 39.9042],
'lon': [-118.2437, -115.1398, 116.4074],
'city': ['Los Angeles', 'Las Vegas', 'Beijing'],
'value':
}
df = pd.DataFrame(data)
# Initialize Kepler.gl map
# An empty map is created by default. You can also pass data and config here.
# Ensure MAPBOX_API_KEY is set as an environment variable for full basemap functionality.
# For example: os.environ['MAPBOX_API_KEY'] = 'YOUR_MAPBOX_ACCESS_TOKEN'
MAPBOX_API_KEY = os.environ.get('MAPBOX_API_KEY', '') # Replace with your token if not set as env var
map_1 = KeplerGl(height=400)
# Add data to the map
map_1.add_data(data=df, name='cities_data')
# Display the map (in a Jupyter environment)
# map_1 # Uncomment this line in a Jupyter notebook to display the map
# Optionally, save the map to an HTML file
# map_1.save_to_html(file_name='my_keplergl_map.html', config=map_1.config)
Debug
Known issues
gotchaA Mapbox API key is often required for displaying base maps in Kepler.gl. Without a valid key (either passed in the constructor or set as an environment variable), maps may not render correctly or may default to a limited style.fixObtain a free access token from Mapbox.com and set it as the `MAPBOX_API_KEY` environment variable, or pass it explicitly to the `KeplerGl` constructor via the `mapbox_api_key` argument if available or through the config object.
affects: All versions
gotchaFor JupyterLab versions prior to 3, or if encountering display issues, manual installation of JupyterLab extensions like `@jupyter-widgets/jupyterlab-manager` and `keplergl-jupyter` might be necessary. For `keplergl > 0.3.0` with JupyterLab 3, these extensions are generally not required.fixFor JupyterLab 3 and `keplergl > 0.3.0`, ensure `pip install keplergl` is done. For older JupyterLab versions, consult the official `kepler.gl-jupyter` README for specific `jupyter labextension install` commands and required `node` versions.
affects: <=0.3.0, especially with JupyterLab < 3
gotchaKepler.gl is optimized for data in the WGS84 (latitude, longitude) coordinate system (EPSG 4326). Data in other projections should be reprojected to WGS84 before being added to the map to ensure accurate visualization.fixUse libraries like GeoPandas to reproject your data to EPSG 4326 (e.g., `gdf.to_crs(epsg=4326, inplace=True)`).
affects: All versions
deprecatedThe `keplergl` library currently uses the `pkg_resources` package, which is deprecated in `setuptools` and will issue a `UserWarning` in newer Python environments. This indicates a dependency on an outdated API.fixA fix (migration to `importlib.resources`) is in progress in the upstream repository. Users may need to upgrade to a future `keplergl` release once this change is incorporated and released.
affects: 0.3.7 and potentially earlier, when used with `setuptools >= 81`
gotchaWhile PyPI lists broad Python 3 support (3.6-3.12), some users have reported specific Python version incompatibilities (e.g., Python 3.11 with older `keplergl` versions), recommending specific environment setups for stability.fixIf encountering installation or runtime errors, consider using Python 3.9 or 3.10, or refer to the `keplergl` GitHub issues and documentation for known compatibility notes with newer Python releases.
affects: Specific combinations of Python environment and keplergl versions.
Upgrade
Version history
0.3.7latest on PyPI · released Feb 1, 2025
Audit
Dependencies
ipywidgets>=7.0.0requiredRequired for the Jupyter widget functionality.
pandasoptionalCommonly used for data handling (DataFrames) before visualization in Kepler.gl.
geopandasoptionalCommonly used for handling geospatial data (GeoDataFrames) with Kepler.gl.