---
title: Install and run Deephaven with pip
sidebar_label: pip
---

[pip](https://pypi.org/project/pip/) is the most popular package manager for Python. Like with other Python packages, you can use it to install Deephaven.

> [!NOTE]
> pip-installed Deephaven is not recommended for production applications. For other installation options more suited for production, see:
>
> - [Docker quickstart](./docker-install.md): Run Deephaven from Docker
> - [Build from source](./launch-build.md): Build Deephaven from source code
> - [Production application](./production-application.md): Run the production application (build artifacts)

## Supported operating systems

Deephaven is only supported on:

- Linux
- MacOS
- Windows 10 or 11 (requires [WSL 2 (Windows Subsystem for Linux v2)](https://learn.microsoft.com/en-us/windows/wsl/install))

## Prerequisites

pip-installed Deephaven requires the following package versions:

| Package | Recommended Version | Required Version |
| ------- | ------------------- | ---------------- |
| java    | latest LTS          | >= 17            |
| python  | latest LTS          | >= 3.9           |

Once the prerequisite packages have been installed, you must also set your `JAVA_HOME` environment variable appropriately.

Once you've completed these steps, you can install Deephaven with pip:

```bash
pip3 install --upgrade setuptools wheel
pip3 install deephaven-server
```

> [!NOTE]
> Deephaven recommends the use of [virtual environments](https://docs.python.org/3/library/venv.html) when installing Python packages.

## 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 CLI. The Deephaven CLI is just a wrapper around the Python API, so both methods are equivalent in functionality.

### From Python

Start Deephaven from Python with the following code:

```python skip-test
from deephaven_server import Server

# Start a server with 4GB RAM on port 10000 and the default PSK authentication
s = Server(port=10000, jvm_args=["-Xmx4g"]).start()
```

If no pre-shared key is specified, the server generates a random one when started. You can instead specify the key as another JVM argument:

```python skip-test
from deephaven_server import Server

# Start a server with 4GB RAM on port 10000 and `PythonR0cks!` as the pre-shared key
s = Server(port=10000, jvm_args=["-Xmx4g", "-Dauthentication.psk=PythonR0cks!"]).start()
```

You can also enable [anonymous authentication](../how-to-guides/authentication/auth-anon.md), which allows you to connect to the server without a pre-shared key:

```python skip-test
from deephaven_server import Server

# Start a server with 4GB RAM on port 10000 and anonymous authentication
s = Server(
    port=10000,
    jvm_args=[
        "-Xmx4g",
        "-DAuthHandlers=io.deephaven.auth.AnonymousAuthenticationHandler",
    ],
).start()
```

> [!NOTE]
> Anonymous authentication provides no application security.

### From the command line

When Deephaven is installed with pip, it comes with a command line interface (CLI). The CLI allows you to start Deephaven servers without instantiating a Python script or using the Python interpreter.

The following command shows a basic usage of the Deephaven CLI:

```bash
# Start a server with 4GB RAM on port 10000 and the default PSK authentication
deephaven server --port 10000 --jvm-args "-Xmx4g"
```

There are a number of available options:

- `--help`: Show a help message and exit.
- `server`: Start a Deephaven server. Additional options include:
  - `--host TEXT`: The host on which to start the server. Default is `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. For example, `-Xmx4g` to allocate 4GB of memory,
  - `--browser` / `--no-browser`: Whether or not to open a browser automatically. Default is `--browser`, which automatically opens your default browser when launching Deephaven.
  - `--extra-classpath TEXT`: Additional classpath entries to add to the server's classpath.
  - `--help`: Show a help message about the `server` command and exit.

For example, the following command sets the pre-shared key to `PythonR0cks!`:

```bash
# Start a server with 4GB RAM on port 10000 and `PythonR0cks!` as the pre-shared key
deephaven server --port 10000 --jvm-args "-Xmx4g -Dauthentication.psk=PythonR0cks!"
```

The following command starts a server with anonymous authentication:

```bash
# Start a server with 4GB RAM on port 10000 and anonymous authentication
deephaven server --port 10000 --jvm-args "-Xmx4g -DAuthHandlers=io.deephaven.auth.AnonymousAuthenticationHandler"
```

## M2 Macs

If you're trying to use pip-installed Deephaven on an M2 MacBook, you must add the argument `"-Dprocess.info.system-info.enabled=false"` to the `jvm_args` list, as in:

```python skip-test
s = Server(port=10000, jvm_args=["-Xmx4g", "-Dprocess.info.system-info.enabled=false"])
```

```bash
deephaven server --port 10000 --jvm-args "-Xmx4g -Dprocess.info.system-info.enabled=false"
```

## Example scripts

This section contains a couple of scripts that demonstrate how to use Deephaven with pip.

> [!CAUTION]
> You **must** start the Deephaven server **before** importing any Deephaven packages or performing any Deephaven operations. If you import Deephaven packages before starting the server, you will encounter errors.

This script creates three streaming tables. The first table (`t`) steadily increases in size, the second table (`t_last`) contains the most recent timestamp for each label, and the third table (`t_join`) joins the most recent timestamp onto the first table.

```python ticking-table order=null
from deephaven import time_table

t = time_table("PT1S").update("A = i%2==0 ? `A` : `B`")
t_last = t.last_by("A")
t_join = t.natural_join(t_last, on="A", joins=["LastTime=Timestamp"])

print(t_join)
```

When running Python scripts from the command line, it's recommended to do so in [interactive mode](https://docs.python.org/3/tutorial/interpreter.html#interactive-mode) so the Python session stays up and running. This ensures the Deephaven server does not stop when the script finishes executing:

```bash
# Interactive mode is enabled with the `-i` flag
python3 -i example.py
```

![The server has been started via the command line](../assets/how-to/pip-2.png)
![The Deephaven web UI](../assets/how-to/pip-1.png)

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:

```python order=left,right,table
from deephaven import new_table
from deephaven.column import string_col, int_col
from deephaven.constants import NULL_INT

left = new_table(
    [
        string_col(
            "LastName", ["Rafferty", "Jones", "Steiner", "Robins", "Smith", "Rogers"]
        ),
        int_col("DeptID", [31, 33, 33, 34, 34, NULL_INT]),
        string_col(
            "Telephone",
            [
                "(347) 555-0123",
                "(917) 555-0198",
                "(212) 555-0167",
                "(952) 555-0110",
                None,
                None,
            ],
        ),
    ]
)

right = new_table(
    [
        int_col("DeptID", [31, 33, 34, 35]),
        string_col("DeptName", ["Sales", "Engineering", "Clerical", "Marketing"]),
        string_col(
            "Telephone",
            ["(646) 555-0134", "(646) 555-0178", "(646) 555-0159", "(212) 555-0111"],
        ),
    ]
)

table = left.join(
    table=right, on=["DeptID"], joins=["DeptName,DeptTelephone=Telephone"]
)
```

## What to do next?

import { TutorialCTA } from '@theme/deephaven/CTA';

<div className="row">
<TutorialCTA to="/core/docs/getting-started/crash-course/overview" />
</div>

## Related documentation

- [Build and launch Deephaven from source code](./launch-build.md)
- [Create a new table](../how-to-guides/new-and-empty-table.md#new_table)
- [Joins: Exact and Relational](../how-to-guides/joins-exact-relational.md)
- [Joins: Time-Series and Range](../how-to-guides/joins-timeseries-range.md)
- [How to install Python packages](../how-to-guides/install-and-use-python-packages.md)