Use Deephaven in Jupyter
This guide shows you how to use Deephaven from Jupyter. Jupyter notebooks are powerful tools for sharing data science workflows with others through easy-to-follow interactive cells.
You can use Deephaven directly from Python with pip-installed Deephaven or the Python client. For either option, Deephaven also provides widgets that display live Deephaven tables and figures in your notebook. For a guided, end-to-end walkthrough of pip-installed Deephaven in Jupyter, see the Jupyter quickstart.
Set up Jupyter and Deephaven
You can run Jupyter as either Jupyter Notebook or JupyterLab. Both work for Deephaven, so you can choose whichever suits your needs better. See Project Jupyter's installation guide to get started with Jupyter.
How you install Deephaven for Jupyter depends on how you use Deephaven from Python:
- Pip-installed Deephaven runs the Deephaven server and your queries inside your notebook's Python process. This option requires Java.
- The Python client (
pydeephaven) connects over gRPC to a Deephaven server that is already running elsewhere, such as in Docker or on a remote machine.
Pick the one that matches where your server runs. This guide covers both. Whichever you pick, install every package in this section into the same Python environment that runs Jupyter, so your notebook can import them.
pip-installed Deephaven
Set up Deephaven in your Python environment. To get started, follow the instructions in the Install guide for pip.
To plot with Deephaven Express, also install deephaven-plugin-plotly-express in the same environment before you start the Deephaven server in your notebook:
The Python client
Install Deephaven's Python client with pip:
You can also build it from source. For instructions, see the pydeephaven page on PyPI.
deephaven-ipywidgets
Both options use deephaven-ipywidgets, a Python package that displays Deephaven tables, figures, and other Deephaven objects in Jupyter as widgets. Without it, Jupyter shows only a text representation of a Deephaven table or figure, not an interactive view. Install it with pip:
You can also install the widget package together with the Deephaven package for your option, in one step:
- For pip-installed Deephaven,
pip3 install "deephaven-ipywidgets[server]"also installsdeephaven-server. - For the Python client,
pip3 install "deephaven-ipywidgets[client]"also installspydeephaven.
Launch Jupyter
If you use Jupyter Notebook, start it with:
If you use JupyterLab, start it with:
From there, create a notebook.
Display tables and figures
pip-installed Deephaven
With pip-installed Deephaven, start a Deephaven server in the notebook first, then use deephaven-ipywidgets to display Deephaven tables or figures (plots).
Caution
You must create a deephaven_server.Server before importing the deephaven package or any module that imports it. If you import deephaven first, the import raises a RuntimeError.
Run the following code in a cell before you work with tables or figures. It starts a Deephaven server on port 10000 with anonymous authentication:
Note
Anonymous authentication provides no application security.
You display tables and figures by wrapping them in a DeephavenWidget from the deephaven-ipywidgets package.
For example, to create a ticking table with time_table and display it:

The table ticks in the notebook just as it does in the Deephaven IDE: a new row appears every second.
You can also create a figure with plot_xy and display it:

This example uses the built-in plotting API, which is no longer under active development. For most plotting, use Deephaven Express. Deephaven Express needs the deephaven-plugin-plotly-express package, installed before you start the server. The plotting overview compares the options.
To display a Deephaven Express figure, pass it to DeephavenWidget the same way:
The widget is an iframe that your browser loads from the Deephaven server. By default, DeephavenWidget uses http://localhost:{port}, where {port} is the port the embedded Server runs on. If your browser reaches the server at a different address, such as when Jupyter runs in a Docker container, set the DEEPHAVEN_IPY_URL environment variable to that address before you create a DeephavenWidget. For example, if the server is mapped to port 1234 on your host:
The Python client
Use the Python client to connect to a Deephaven server that is already running. For a local server on port 10000 with anonymous authentication, you can create a session without arguments:
If the server uses pre-shared key authentication, as a default Docker server does, pass the key:
To connect to a remote server or a server that uses another type of authentication, see the Session Pydoc. For a full introduction to the client, see the Python client quickstart.
To display a table you create through the session, pass it to DeephavenWidget. The widget handles the rest. The example below also calls bind_table, which is optional. It gives the table a name, my_time_table, that the web IDE and other sessions can use. Leave that line out if you only want to display the table:
The widget loads the table from http://{host}:{port}, using the session's host and port. If your browser reaches the server at a different address, set DEEPHAVEN_IPY_URL as described for pip-installed Deephaven.