pydeck

0.9.1 verified Tue May 12 auth: no python install: verified

pydeck is a Python binding for deck.gl, a WebGL-powered framework for large-scale interactive data visualization. It is optimized for Jupyter environments, enabling users to create powerful geospatial visualizations with a declarative Python API, largely obviating the need for extensive JavaScript knowledge. The current stable version is 0.9.1, which aligns with deck.gl v9.0, and new releases generally follow the major version updates of the underlying deck.gl library.

pip install pydeck

Common errors

error Pydeck visualization not rendering / blank output in Jupyter ↓

cause This often occurs due to a JavaScript error in the browser's console, incorrect or omitted layer arguments, or a missing internet connection, none of which pydeck typically raises as Python exceptions directly. Jupyter-specific features for bidirectional interaction are also not supported in pydeck v0.9+ without explicit `Deck.show()` calls and enabled extensions.

fix

Check your browser's developer console for JavaScript errors related to deck.gl or pydeck. Ensure all layer arguments are correct and present according to the deck.gl layer catalog. Verify you have an active internet connection if using online basemaps or data. If in Jupyter, ensure jupyter nbextension or jupyter labextension for pydeck is correctly installed and enabled. For interactive features, use r.show() instead of r.to_html() within a Jupyter environment.

error AttributeError: 'Deck' object has no attribute 'deck_widget' ↓

cause This error typically arises when attempting to use a `pydeck.Deck` object in a way that expects a specific Jupyter widget attribute (`deck_widget`) which might not be available, or when using `st.pydeck_chart()` in Streamlit with an incompatible `pydeck` version or an incorrectly initialized `Deck` object.

fix

Ensure you are using st.pydeck_chart(map_object) directly with the pydeck.Deck instance in Streamlit, or if in a Jupyter context, that r.show() is called correctly and the Jupyter extensions are properly enabled. This error might also indicate a version mismatch between pydeck and streamlit or other dependencies, consider updating or rolling back pydeck.

error TypeError: __init__() got an unexpected keyword argument 'mapbox_key' ↓

cause This error occurs because the `mapbox_key` argument is no longer directly accepted in the `pydeck.Deck` constructor in newer versions of pydeck (from v0.6 onwards). Basemap tiles are provided by Carto by default, or Mapbox/Google Maps keys should be set via environment variables.

fix

Instead of passing mapbox_key directly, set the MAPBOX_API_KEY or GOOGLE_MAPS_API_KEY as an environment variable before running your application. For example, export MAPBOX_API_KEY='YOUR_MAPBOX_KEY' in your terminal. Alternatively, use pydeck.settings.set_mapbox_api_key('YOUR_MAPBOX_KEY') if you need to set it programmatically.

error AttributeError: partially initialized module 'pydeck' has no attribute 'ViewState' (most likely due to a circular import) ↓

cause This `AttributeError` often points to a circular import issue, frequently caused by naming a Python script file `pydeck.py` (or a similar name that clashes with the library's module name) in the same directory as the script where you are trying to import `pydeck` components.

fix

Rename your Python script file to something other than pydeck.py (e.g., my_pydeck_app.py) to avoid conflicting with the installed pydeck library. Ensure your script's directory is not inadvertently added to Python's import path in a way that prioritizes your script over the installed library.

error TypeError: vars() argument must have __dict__ attribute ↓

cause This error occurs when `pydeck`'s internal serialization logic (specifically `default_serialize`) attempts to call `vars()` on an object, typically a weakref to a Pandas DataFrame, that no longer possesses a `__dict__` attribute. This is a known compatibility issue with Pandas 3.x, where DataFrames no longer expose a `__dict__`.

fix

This is a compatibility issue that requires an update to the pydeck library to support Pandas 3.x. If possible, downgrade Pandas to version 2.x or earlier until a pydeck version with a fix is released. Alternatively, ensure your DataFrame only contains the necessary columns for pydeck to avoid unexpected serialization paths.

Warnings

breaking As of pydeck v0.9+, certain advanced Jupyter-specific features, such as binary data transportation, interactive data selection, and real-time data updates, are not currently supported. While `pydeck` still works in Jupyter, users relying on these interactive capabilities may experience a regression or need to adjust their workflows. ↓

fix Review documentation for alternatives or consider rendering static HTML outputs for complex interactive scenarios. For basic interactivity (hover, click events), these are still supported, but might not be as deeply integrated as in previous versions.

gotcha pydeck does not always raise Python errors for incorrect or omitted layer arguments. If a visualization fails to render or behaves unexpectedly, users should typically inspect the browser's developer console for JavaScript errors, as `pydeck` translates Python objects to JavaScript for rendering. ↓

fix Always check the browser's JavaScript console for errors when encountering rendering issues. Refer to the official deck.gl layer catalog for detailed argument specifications, and pydeck examples for Pythonic translations.

gotcha Dataframe column names used in `get_` accessors (e.g., `get_position`, `get_fill_color`) should ideally be sanitized to avoid hyphens or whitespace. The underlying JavaScript expression parser may interpret these as arithmetic operations (e.g., `datum.lng - datum.new` instead of `datum['lng-new']`), leading to rendering failures. ↓

fix Rename dataframe columns to use snake_case or remove special characters before passing them to pydeck layers, for example, `df.columns = df.columns.str.replace('[^A-Za-z0-9_]+', '', regex=True)`.

gotcha If data values in a DataFrame column are integers and are used by `get_` accessors that expect floating-point numbers (e.g., for coordinates or elevations), it might lead to unexpected behavior or rendering issues. ↓

fix Explicitly convert integer columns to float types (e.g., `df['column_name'] = df['column_name'].astype(float)`) if they are intended for graphical properties that might require floating-point precision.

gotcha While pydeck defaults to Carto basemaps, if you intend to use Mapbox or Google Maps, you will need to provide an API key. These keys can be passed directly to the `Deck` object or set as environment variables (`MAPBOX_API_KEY`, `GOOGLE_MAPS_API_KEY`). ↓

fix Set `MAPBOX_API_KEY` or `GOOGLE_MAPS_API_KEY` as environment variables or pass them via the `api_keys` parameter in the `pydeck.Deck` constructor (e.g., `api_keys={'mapbox': 'YOUR_KEY'}`).

gotcha Executing pydeck within a Jupyter environment requires Jupyter (and typically ipykernel) to be installed in the Python environment. If Jupyter is not installed or not accessible, any attempts to render pydeck visualizations in a Jupyter context will fail with a 'command not found' error. ↓

fix Ensure Jupyter and ipykernel are installed (e.g., `pip install jupyterlab ipykernel`) and that the Jupyter executable is in your system's PATH, or use a Python environment where they are available.

Install

pip install pydeck
jupyter nbextension install --sys-prefix --symlink --overwrite --py pydeck
jupyter nbextension enable --sys-prefix --py pydeck

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.42s 113.2M

3.10 alpine (musl) dependency_conflict - - - -

3.10 alpine (musl) - - - -

3.10 alpine (musl) - - 0.36s 104.6M

3.10 slim (glibc) wheel 4.2s 0.33s 109M

3.10 slim (glibc) dependency_conflict - 4.2s - -

3.10 slim (glibc) - - - -

3.10 slim (glibc) - - 0.36s 101M

3.11 alpine (musl) wheel - 0.56s 121.0M

3.11 alpine (musl) dependency_conflict - - - -

3.11 alpine (musl) - - - -

3.11 alpine (musl) - - 0.58s 112.4M

3.11 slim (glibc) wheel 4.0s 0.54s 117M

3.11 slim (glibc) dependency_conflict - 4.0s - -

3.11 slim (glibc) - - - -

3.11 slim (glibc) - - 0.47s 108M

3.12 alpine (musl) wheel - 0.49s 109.4M

3.12 alpine (musl) dependency_conflict - - - -

3.12 alpine (musl) - - - -

3.12 alpine (musl) - - 0.48s 100.8M

3.12 slim (glibc) wheel 3.8s 0.52s 105M

3.12 slim (glibc) dependency_conflict - 3.8s - -

3.12 slim (glibc) - - - -

3.12 slim (glibc) - - 0.49s 96M

3.13 alpine (musl) wheel - 0.42s 108.9M

3.13 alpine (musl) dependency_conflict - - - -

3.13 alpine (musl) - - - -

3.13 alpine (musl) - - 0.47s 100.2M

3.13 slim (glibc) wheel 4.0s 0.50s 104M

3.13 slim (glibc) dependency_conflict - 3.9s - -

3.13 slim (glibc) - - - -

3.13 slim (glibc) - - 0.49s 96M

3.9 alpine (musl) wheel - 0.35s 121.0M

3.9 alpine (musl) dependency_conflict - - - -

3.9 alpine (musl) - - - -

3.9 alpine (musl) - - 0.32s 112.4M

3.9 slim (glibc) wheel 4.7s 0.38s 120M

3.9 slim (glibc) dependency_conflict - 4.7s - -

3.9 slim (glibc) - - - -

3.9 slim (glibc) - - 0.30s 111M

Imports

Deck
```
from pydeck import Deck
```
Layer
```
from pydeck import Layer
```
ViewState
```
from pydeck import ViewState
```
pdk
```
import pydeck as pdk
```
Commonly aliased as `pdk` for brevity and convention.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to create a basic 3D heatmap using pydeck's HexagonLayer. It fetches data from a URL, defines a layer with visualization properties, sets an initial camera view, and then renders the map. The map can be displayed directly in a Jupyter environment or exported to a standalone HTML file. An optional Mapbox API key is included for base map rendering.

import pydeck as pdk
import pandas as pd
import os

# Sample data (e.g., 2014 locations of car accidents in the UK)
UK_ACCIDENTS_DATA = (
    'https://raw.githubusercontent.com/uber-common/'
    'deck.gl-data/master/examples/3d-heatmap/heatmap-data.csv'
)

# Define a layer to display on a map
layer = pdk.Layer(
    'HexagonLayer',
    data=UK_ACCIDENTS_DATA,
    get_position=['lng', 'lat'],
    auto_highlight=True,
    elevation_scale=50,
    pickable=True,
    elevation_range=[0, 3000],
    extruded=True,
    coverage=1
)

# Set the viewport location
view_state = pdk.ViewState(
    longitude=-1.415,
    latitude=52.2323,
    zoom=6,
    min_zoom=5,
    max_zoom=15,
    pitch=40.5,
    bearing=-27.36
)

# Render the map
r = pdk.Deck(
    layers=[layer],
    initial_view_state=view_state,
    api_keys={'mapbox': os.environ.get('MAPBOX_API_KEY', '')} # Or Google Maps API key
)

# To display in a Jupyter environment, use r.show().
# To save to an HTML file:
r.to_html('pydeck_quickstart.html')