Install & Compatibility
Where this runs
tested against v0.9.3 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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')
Debug
Known issues
breakingAs 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.fixReview 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.
affects: 0.9.0 and later
gotchapydeck 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.fixAlways 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.
affects: All versions
gotchaDataframe 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.fixRename 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)`. affects: All versions
gotchaIf 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.fixExplicitly 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.
affects: Older versions (pre-0.8.x) particularly affected, but good practice for all.
gotchaWhile 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`).fixSet `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'}`). affects: All versions
gotchaExecuting 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.fixEnsure 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.
affects: All versions
Errors
Common errors & fixes
Pydeck visualization not rendering / blank output in Jupyter
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.
fixCheck 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.
AttributeError: 'Deck' object has no attribute 'deck_widget'
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.
fixEnsure 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`.
TypeError: __init__() got an unexpected keyword argument 'mapbox_key'
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.
fixInstead 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. AttributeError: partially initialized module 'pydeck' has no attribute 'ViewState' (most likely due to a circular import)
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.
fixRename 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.
TypeError: vars() argument must have __dict__ attribute
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__`.
fixThis 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.
Upgrade
Version history
0.9.3latest on PyPI · released Jul 2, 2026
Audit
Dependencies
pandasoptionalCommonly used for data handling with pydeck layers.
geopandasoptionalOften used for geospatial data processing before visualization with pydeck.