{"id":14656,"library":"keplergl","title":"Kepler.gl Python Jupyter Widget","description":"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.","status":"active","version":"0.3.7","language":"en","source_language":"en","source_url":"https://github.com/keplergl/kepler.gl/tree/master/bindings/kepler.gl-jupyter","tags":["geospatial","visualization","jupyter","maps","data science","interactive"],"install":[{"cmd":"pip install keplergl","lang":"bash","label":"PyPI Installation"},{"cmd":"conda install -c conda-forge keplergl","lang":"bash","label":"Conda Installation (Recommended for Geospatial Dependencies)"}],"dependencies":[{"reason":"Required for the Jupyter widget functionality.","package":"ipywidgets>=7.0.0","optional":false},{"reason":"Commonly used for data handling (DataFrames) before visualization in Kepler.gl.","package":"pandas","optional":true},{"reason":"Commonly used for handling geospatial data (GeoDataFrames) with Kepler.gl.","package":"geopandas","optional":true}],"imports":[{"symbol":"KeplerGl","correct":"from keplergl import KeplerGl"}],"quickstart":{"code":"import pandas as pd\nfrom keplergl import KeplerGl\nimport os\n\n# Create a sample DataFrame\ndata = {\n    'lat': [34.0522, 36.1699, 39.9042],\n    'lon': [-118.2437, -115.1398, 116.4074],\n    'city': ['Los Angeles', 'Las Vegas', 'Beijing'],\n    'value':\n}\ndf = pd.DataFrame(data)\n\n# Initialize Kepler.gl map\n# An empty map is created by default. You can also pass data and config here.\n# Ensure MAPBOX_API_KEY is set as an environment variable for full basemap functionality.\n# For example: os.environ['MAPBOX_API_KEY'] = 'YOUR_MAPBOX_ACCESS_TOKEN'\nMAPBOX_API_KEY = os.environ.get('MAPBOX_API_KEY', '') # Replace with your token if not set as env var\n\nmap_1 = KeplerGl(height=400)\n\n# Add data to the map\nmap_1.add_data(data=df, name='cities_data')\n\n# Display the map (in a Jupyter environment)\n# map_1 # Uncomment this line in a Jupyter notebook to display the map\n\n# Optionally, save the map to an HTML file\n# map_1.save_to_html(file_name='my_keplergl_map.html', config=map_1.config)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<=0.3.0, especially with JupyterLab < 3"},{"fix":"Use libraries like GeoPandas to reproject your data to EPSG 4326 (e.g., `gdf.to_crs(epsg=4326, inplace=True)`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"0.3.7 and potentially earlier, when used with `setuptools >= 81`"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Specific combinations of Python environment and keplergl versions."}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[],"ecosystem":"pypi"}