Install and run Deephaven with pip

pip is the most popular package manager for Python. This guide shows how to install Deephaven with pip, start a Deephaven server from Python or the command line, and run example queries in it.

Supported operating systems

Deephaven supports only the following operating systems:

• Linux
• macOS
• Windows 10 or 11 (requires WSL 2 (Windows Subsystem for Linux v2))

Prerequisites

pip-installed Deephaven requires:

After installing Java and Python, set the JAVA_HOME environment variable to your Java installation.

Install Deephaven

Deephaven recommends installing Python packages in a virtual environment. To create and activate one:

Upgrade setuptools and wheel, then install the deephaven-server package:

Start a Deephaven server

There are two ways to start a Deephaven server after installing it with pip. You can start it from Python (either a script or an interactive session) or from the command line using the Deephaven command line interface (CLI). The Deephaven CLI is a wrapper around the Python API.

By default, the server uses pre-shared key (PSK) authentication, so the web IDE and clients need a password-like key to connect. If you don't set a key, the server generates a random one at startup.

From Python

When you start the server from Python, it doesn't print the generated key to the console, so set your own key with a JVM argument.

The Server constructor takes the following parameters: host, port, jvm_args, default_jvm_args, and extra_classpath. They correspond to the CLI's --host, --port, --jvm-args, --default-jvm-args, and --extra-classpath options, described in From the command line. The constructor takes lists where the CLI takes space-separated strings. The constructor has no equivalent of --browser.

The following code starts the server and sets the key to PythonR0cks!:

After the server starts, open the web IDE at http://localhost:10000/ide/ and enter the key you set. If you chose a different port, use it in place of 10000.

You can also enable anonymous authentication, which allows you to connect to the server without a pre-shared key:

The Deephaven server runs only as long as the Python process that started it. When you run a Python script from the command line, use interactive mode so the Python session and the Deephaven server keep running after the script finishes. For example, if you save either startup snippet above as example.py, run:

From the command line

Installing Deephaven with pip also installs the deephaven CLI, which starts a Deephaven server without a Python script.

The following command starts a server with the Deephaven CLI:

The command prints the URL of the web IDE, including the pre-shared key, and by default opens that URL in your browser so you're logged in automatically. With --no-browser, open the printed URL yourself. The server keeps running until you press Ctrl+C.

The deephaven CLI accepts the following options and commands:

• --help: Show a help message and exit.
• server: Start a Deephaven server. Additional options include:
  • --host TEXT: The network interface the server binds to. If you don't set it, the server listens on all network interfaces, and the printed URL uses localhost.
  • --port INTEGER: The port on which to start the server. Default is 10000.
  • --jvm-args TEXT: Additional JVM arguments to pass to the server, separated by spaces. For example, -Xmx4g sets the maximum heap size to 4 GB.
  • --default-jvm-args TEXT: Advanced JVM arguments to use in place of the defaults that Deephaven recommends (for example, garbage collector settings). Most users don't need this.
  • --browser / --no-browser: Whether to open your default browser when the server starts. Default is --browser.
  • --extra-classpath TEXT: Additional classpath entries to add to the server's classpath. Separate multiple entries with spaces, not :. Each entry can be a glob pattern, such as /path/to/libs/*.jar. Entries that match no file are silently ignored.
  • --help: Show a help message about the server command and exit.

For example, the following command sets the pre-shared key to PythonR0cks! instead of a random one:

The following command starts a server with anonymous authentication, which provides no application security:

Example scripts

This section contains two scripts to run on your pip-installed Deephaven server. If you started the server with the CLI, paste these scripts into the web IDE. If you started it from Python, run them in that Python session after the server has started. To run a script as a standalone file instead, add it to example.py after the startup code from the From Python section. Put the script's deephaven imports after the line that starts the server. Then run the file with python3 -i example.py.

This script creates three ticking tables (tables that update live as new data arrives) with time_table, last_by, and natural_join:

• t adds a row every second, so it steadily grows.
• t_last holds the most recent row for each value in column A.
• t_join adds that most recent Timestamp to t as the LastTime column.

If you run the script with python3 -i, the terminal shows the server starting and a one-line summary of t_join, including its row count and the start of its column list. In every case, the web IDE shows the three ticking tables:

This next script creates a left table with employee data and a right table with department data. It then joins them on the DeptID column with join. Run it the same way as the first script.

What to do next

Related documentation

• Build and launch Deephaven from source code
• Create a new table
• Joins: Exact and Relational
• Joins: Time-Series and Range
• How to install Python packages