Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
Development Guide
This guide explains how to set up kepler.gl for Jupyter for local development.
Prerequisites
- Python >= 3.9
- Node.js >= 20 (for building the frontend)
- JupyterLab >= 4.0 or Notebook >= 7.0
Installation
Navigate to the bindings/python directory:
cd bindings/python
1. Install JavaScript dependencies and build the frontend
npm install
npm run build
2. Install Python package in development mode
Using uv (recommended):
uv sync --dev
Or using pip:
pip install -e ".[dev]"
3. Start Jupyter
# With uv
uv run jupyter lab
# Or with pip
jupyter lab
Development with Hot Reload
For active development with automatic rebuilding of the TypeScript/JavaScript:
# Terminal 1: Watch for TypeScript changes
npm run dev
# Terminal 2: Run Jupyter
uv run jupyter lab
The npm run dev command watches for changes in the src/ directory and automatically rebuilds the widget JavaScript.
Quick Test
from keplergl import KeplerGl
# Create a map
map = KeplerGl(height=400)
map
Running Tests
uv run pytest
Available npm Scripts
npm run build- Build TypeScript tokeplergl/static/npm run dev- Build with watch mode for developmentnpm run typecheck- Run TypeScript type checkingnpm run lint- Run ESLint on source files
Publishing to PyPI
Publishing is done manually via GitHub Actions using the "Run workflow" button.
Version Format
The version in pyproject.toml determines what type of release you can publish:
- Prerelease versions: Must have a suffix like
a,b,rc, ordevfollowed by a number- Examples:
0.4.0a1(alpha),0.4.0b1(beta),0.4.0rc1(release candidate),0.4.0.dev1(development)
- Examples:
- Official versions: Clean semantic versions without any suffix
- Examples:
0.4.0,1.0.0
- Examples:
Publishing Steps
Update the version in both files:
pyproject.toml(line:version = "x.x.x")keplergl/_version.py(line:__version__ = "x.x.x")- On a kepler.gl major release, also update
DEFAULT_KEPLER_GL_CDN_VERSIONinkeplergl/_html_export.pyto match the new major version.
Go to GitHub Actions → "Build and Publish KeplerGL Python Package" workflow
Click "Run workflow" and select the appropriate option:
- Prerelease (checked by default): Publishes to PyPI as a prerelease. Version must have a prerelease suffix.
- Official release (unchecked): Publishes to PyPI as an official release. Version must be a clean version.
The workflow will:
- Build and test the package
- Validate that the version format matches the publish type
- Publish to PyPI if validation passes
Validation Rules
| Checkbox | Version | Result |
|---|---|---|
| ✓ Prerelease | 0.4.0a1 |
✅ Publishes |
| ✓ Prerelease | 0.4.0 |
❌ Fails (version must have prerelease suffix) |
| ☐ Official | 0.4.0 |
✅ Publishes |
| ☐ Official | 0.4.0a1 |
❌ Fails (version must not have prerelease suffix) |