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:

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 the pip install line.

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.

  1. Create a directory for your deployment and save the following as Dockerfile in it:

  2. Build the image and run it:

    For more docker run options, see Configure the Deephaven Docker application.

    If you use Docker Compose, save the following as docker-compose.yml in 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 docker commands:

  3. 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 to pack-plugins.sh. JS plugins installed with pip appear 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 the server image installs with pip.

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:

  1. Get the plugin's object on the server by its variable name from Session.exportable_objects.
  2. Wrap it in a PluginClient with Session.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.

Remote file sourcing

You can install this plugin with pip:

Authentication

Authentication plugins have a more complex installation process than other plugins. See the following guides for details:

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, which pydeephaven removed in version 0.37.0, so it needs updating before it runs with current clients. It uses Python's pickle module, 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, which pydeephaven removed in version 0.37.0, so follow the code in that guide instead.