Kepler.gl Python Jupyter Widget

0.3.7 · active · verified Tue Apr 14

Kepler.gl is an open-source, high-performance geospatial analysis and visualization tool developed by Uber, designed to render large-scale interactive maps. The `keplergl` Python library provides a Jupyter widget to embed and interact with Kepler.gl maps within notebooks. While the Python package is currently at version 0.3.7 on PyPI, its underlying JavaScript core (`kepler.gl`) is actively developed with v3.x releases, and a 0.4.0rc1 pre-release for the Python binding is available, indicating a continuous and active development cadence.

Warnings

gotcha A 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.
Fix: Obtain 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.
gotcha For 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.
Fix: For 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.
gotcha Kepler.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.
Fix: Use libraries like GeoPandas to reproject your data to EPSG 4326 (e.g., `gdf.to_crs(epsg=4326, inplace=True)`).
deprecated The `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.
Fix: A 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.
gotcha While 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.
Fix: If 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.

Install

pip install keplergl PyPI Installation
conda install -c conda-forge keplergl Conda Installation (Recommended for Geospatial Dependencies)

Imports

KeplerGl
```
from keplergl import KeplerGl
```

Quickstart

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)

view raw JSON →