Install and use plugins
This guide covers how to install and use pre-built plugins in Deephaven. A plugin extends the functionality of Deephaven, much as a Python package extends Python. Some plugins are distributed as Python packages, but not every Python package is a plugin. Plugins in Deephaven can extend the functionality of a running server, UI, client API, or all of them.
Deephaven offers several pre-built plugins that extend the platform's functionality, and anyone using Deephaven Community Core can install them. For the plugins you can install, see Available plugins.
Note
To install Linux system packages rather than plugins, see Install packages. To install Python packages, see Install and use Python packages.
To have complete control of the build process, see Build and launch Deephaven from source code.
For information on building your own plugins, see Create your own plugin.
Types of plugins
Deephaven plugins come in four types:
- Server-side plugins extend the Deephaven server. For example, plotting plugins let you plot with Deephaven Express or with Matplotlib and Seaborn. Authentication plugins add authentication methods such as mutual TLS (mTLS).
- UI plugins, also called JavaScript (JS) plugins, extend the Deephaven web IDE. They are JavaScript packages that the server loads and serves to the browser. For example, the theme pack adds IDE color themes.
- Client-side plugins extend Deephaven's client APIs. For example, a plugin can extend the Python client API so the client can manage arbitrary Python objects on the server, or so it can interact with the server using a different serialization format.
- Bidirectional plugins keep a message stream open between a server-side object and a client so that the two can exchange messages. Many also ship a client-side plugin. For example, the remote file source plugin lets Python code on the server import modules from files that a client, such as the Deephaven VS Code extension, provides. See Bidirectional plugin examples.
Install a plugin
Note
Authentication plugins need additional configuration. See Authentication for the guide to each one.
How you install a plugin depends on how it is packaged:
- Python package (with or without JS bundled in its wheel): install it with
pip. See Install with pip. - npm package (a JS component that isn't in a wheel): package it with
pack-plugins.shand copy the result to the directory where the server looks for JS plugins. In Docker, build a custom image on the pre-built Deephaven image, as described in Extend Docker images for JS plugins. For other installations, see Configure JS plugins.
Install with pip
You can install some plugins with pip. Install them into the Python environment the server runs in. The server loads plugins only when it starts, so restart the server after you install a plugin.
In Docker, don't run pip install inside a running container. Add the pip install line to a custom image instead. The server then loads the plugin when the container starts, and the plugin survives container restarts. For example, the following Dockerfile adds the theme pack:
Build and run the image the same way as in Example: install an npm-only JS plugin.
The user interface and remote file sourcing plugins install with pip. The ghcr.io/deephaven/server Docker image already includes deephaven-plugin-ui, deephaven-plugin-plotly-express, and deephaven-plugin-matplotlib, so you don't need to install those there.
For more information on installing Python packages in Deephaven, see Install and use Python packages.
Extend Docker images for JS plugins
Plugins whose JS component is published to npm, rather than bundled in the Python .whl file, need more setup than pip install. To install one in Docker, build a new Docker image based on Deephaven that adds the plugin.
Each plugin's npm package name is the name field of src/js/package.json in its folder of the plugins repository. You can also search npm for the deephaven-js-plugin keyword.
The following Dockerfile is the general template for a plugin with both JavaScript and Python components:
To fill in the template:
- Replace
<plugins>with one or more npm package names, separated by spaces. To pin a version, append@<version>to a name. - Replace
<packages>with the plugin's Python package names. For a JS-only plugin, omit thepip installline.
For how the server discovers JS plugins and how to change the plugin directory, see Configure JS plugins.
Example: install an npm-only JS plugin
The dashboard object viewer plugin adds an IDE panel that displays server objects other than tables and figures. Its JS is published only to npm, as @deephaven/js-plugin-dashboard-object-viewer, so pip can't install it.
-
Create a directory for your deployment and save the following as
Dockerfilein it: -
Build the image and run it:
For more
docker runoptions, see Configure the Deephaven Docker application.If you use Docker Compose, save the following as
docker-compose.ymlin the same directory. It builds the image from your Dockerfile rather than pulling one from the registry:Then build and run with a single command, instead of the two
dockercommands: -
Confirm that the server loaded the plugin. The server lists its JS plugins at
http://localhost:10000/js-plugins/manifest.json:The output lists each JS plugin that the server loaded, by its npm package name. A plugin you packaged appears without any
@<version>suffix you passed topack-plugins.sh. JS plugins installed withpipappear too.Here, the output includes
@deephaven/js-plugin-dashboard-object-viewer. It also includes the JS plugins for Deephaven Express, Matplotlib, and deephaven.ui, which theserverimage installs withpip.
Use a plugin
After installation, each plugin's own documentation covers its API. For example, see deephaven.ui, Deephaven Express, and Matplotlib and Seaborn.
To use a client-side or bidirectional plugin from the Python client:
- Get the plugin's object on the server by its variable name from
Session.exportable_objects. - Wrap it in a
PluginClientwithSession.plugin_client.
For a worked example, see Client-side testing.
Available plugins
The plugins repository
Deephaven hosts a plugins repository that contains many of the official plugins offered. It's a good place to find more information about the plugins and view their source code.
Note
Some plugins are not in the plugins repository but are still available for use. For instance, some authentication plugins are JAR files only available on Maven Central.
Two folders in the plugins repository are of particular interest:
- plugins: Contains the implementation of the plugins. This is where you can find each plugin's source code and additional documentation.
- templates: Contains templates for creating new plugins. This is a great starting point if you want to create your own plugin.
The following sections group some of the available plugins by functionality.
User interface
You can install each of the following user interface plugins with pip. The ghcr.io/deephaven/server image already includes the first three.
deephaven-plugin-ui: A plugin for building real-time dashboards with deephaven.ui.deephaven-plugin-plotly-express: A plugin, Deephaven Express, that makes Plotly Express compatible with Deephaven tables.deephaven-plugin-matplotlib: A plugin that makes Matplotlib and Seaborn compatible with Deephaven tables. See Matplotlib and Seaborn.deephaven-plugin-theme-pack: A plugin that adds UI themes such as Dracula, Night Owl, and Solarized Dark to the Deephaven IDE.deephaven-plugin-tradingview-lightweight: A plugin for creating TradingView Lightweight Charts from Python.
Remote file sourcing
You can install this plugin with pip:
deephaven-plugin-python-remote-file-source: A bidirectional plugin that lets Python code import modules from a remote file source. Use it with the Deephaven VS Code extension to enable local Python workspaces.
Authentication
Authentication plugins have a more complex installation process than other plugins. See the following guides for details:
- Keycloak: A plugin that enables the use of Keycloak and OpenID Connect (OIDC) for authentication.
- mTLS: A plugin that enables mutual TLS (mTLS) authentication.
- Username/password: A plugin that enables username/password authentication.
Bidirectional plugin examples
Bidirectional plugins let you define custom remote procedure call (RPC) methods that clients call to interact with objects on a running server and get objects back. See the following examples:
- Pickle RPC plugin: A plugin to remotely execute methods on a Deephaven server. Its client code imports
pydeephaven.experimental.server_object, whichpydeephavenremoved in version 0.37.0, so it needs updating before it runs with current clients. It uses Python'spicklemodule, which is not secure. Read its README before you adapt it. - Example bidirectional plugin: A minimal bidirectional plugin and a client that uses it. It is an earlier version of the example in Create your own plugin. Its client code imports
pydeephaven.experimental.server_object, whichpydeephavenremoved in version 0.37.0, so follow the code in that guide instead.
Related documentation
- Build and launch Deephaven from source code
- Configure JS plugins
- Configure Keycloak for authentication
- Configure mTLS for Deephaven
- Configure the Deephaven Docker application
- Configure username/password authentication
- Create your own plugin
- Deephaven Express
- deephaven.ui
- Install and use Python packages
- Install packages
- Launch Deephaven from pre-built images
- Matplotlib and Seaborn
- Python client quickstart
PluginClientPydocSessionPydoc