Installing pydeck

There are two steps before using pydeck:

    1. Install the library via pip or conda
    2. Include an API key from Google Maps or Mapbox (Optional)

pydeck requires Python 3.8 or above.

Via pip ^^^^^^^

Note: It is best practice to run this command in a virtual environment <https://docs.python.org/3/library/venv.html#creating-virtual-environments>_.

.. code-block:: bash

    pip install pydeck

Via conda ^^^^^^^^^

.. code-block:: bash

    conda install -c conda-forge pydeck

That's it — pydeck renders visualizations using the deck.gl JavaScript library loaded from a CDN, so no additional Jupyter extension setup is needed for .show() and .to_html().

Getting a Mapbox API key ^^^^^^^^^^^^^^^^^^^^^^^^

By default, pydeck v0.6 onwards provides basemap tiles through Carto.

You can optionally use a Mapbox API key, by registering for Mapbox via this link <https://account.mapbox.com/auth/signup/>. You should then create a new public API token <https://account.mapbox.com/access-tokens/>. You can learn more about Mapbox tokens via their documentation <https://docs.mapbox.com/help/how-mapbox-works/access-tokens/#how-access-tokens-work>_.

You can also use a Google Maps API key in a similar way. Currently Google Maps is not supported for 3D visualizations.

pydeck checks for API keys via environment variables automatically. Both the deck.gl JavaScript convention and the pydeck convention are supported (the deck.gl convention is checked first):

Mapbox: MapboxAccessToken (deck.gl) or MAPBOX_API_KEY (pydeck)
Google Maps: GoogleMapsAPIKey (deck.gl) or GOOGLE_MAPS_API_KEY (pydeck)
Carto: CARTO_API_KEY

For example, to set your Mapbox key:

.. code-block:: bash

    export MapboxAccessToken=pk.your_token_here

If you're already working with deck.gl JavaScript projects, you likely have MapboxAccessToken set and pydeck will pick it up automatically.

Enabling pydeck for Jupyter ^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. NOTE:: The Jupyter widget integration (binary transport, data selection, event handlers, and live .update()) is not currently functional in pydeck v0.9+. See :doc:jupyter for details. The extension setup instructions below are retained for when widget support is restored.

.. commenting out rather than removing — restore when widget support is re-enabled

.. To enable pydeck for Jupyter Notebook:

.. code-block:: bash

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

To enable pydeck for JupyterLab (on Mac/Unix-like systems):

.. code-block:: bash

       jupyter labextension install @jupyter-widgets/jupyterlab-manager
       DECKGL_SEMVER=`python -c "import pydeck; print(pydeck.frontend_semver.DECKGL_SEMVER)"`
       jupyter labextension install @deck.gl/jupyter-widget@$DECKGL_SEMVER

pydeck also works in Google Colab. While you can install pydeck in Google Colab via pip, it is not yet enabled for server use.

Installing from source ^^^^^^^^^^^^^^^^^^^^^^

If you want to install the library from its source:

.. code-block:: bash

    git clone https://github.com/visgl/deck.gl
    cd deck.gl/bindings/pydeck
    make setup-env
    source .venv/bin/activate
    make init

Development ^^^^^^^^^^^

If you want to install pydeck for development, see :doc:contributing.

You can run the local tests to verify that the installation worked via make test.

.. Note on pre-releases ^^^^^^^^^^^^^^^^^^^^

If you are installing a pydeck prerelease and using JupyterLab, you must install an exact version of @deck.gl/jupyter-widget. You can read this version from pydeck itself:

.. code-block:: bash

       DECKGL_SEMVER=`python -c "import pydeck; print(pydeck.frontend_semver.DECKGL_SEMVER)"`
       jupyter labextension install @deck.gl/jupyter-widget@$DECKGL_SEMVER