---
title: Develop a Python Client Query
sidebar_label: Python
---

Welcome to the Client APIs section of the crash course! So far, you've learned how to use Deephaven from the server itself. If you missed any of the previous sections, check out the links below:

- [Ingesting data](../data-in/streaming-kafka.md)
- [Writing queries](../develop-query/deephaven-ide.md)
- [Creating dashboards](../create-dashboard/by-hand.md)

This section of the crash course covers Deephaven Enterprise's client APIs. This guide discusses the Python client, which allows you to:

- Create new workers
- Interact with tables and objects on the server
- Connect to existing Persistent Queries (PQs)
- Create PQs
- Run queries server-side
- And more!

The Enterprise Python client is built on top of the [Community Python client](/core/client-api/python/), giving you access to its rich feature set.

## Installation

Install the Enterprise Python client from the wheel file available in your Deephaven Enterprise installation. If your system administrator has not given you the wheel file directly, you can copy it from the server to your local machine. It is found in the following location on every installation:

```
/usr/illumon/coreplus/latest/py/wheel/deephaven_coreplus_client-VAR::COREPLUS_DHE_VERSION-py3-none-any.whl
```

Deephaven _always_ recommends the use of [virtual environments](https://docs.python.org/3/library/venv.html) for local development. Create and use a new virtual environment, and install the wheel with `pip`:

```bash
python -m venv .venv

./.venv/bin/pip install deephaven_coreplus_client-VAR::COREPLUS_DHE_VERSION-py3-none-any.whl
```

Alternatively, you may install the Deephaven Core+ client from [PyPi](https://pypi.org/project/deephaven-coreplus-client/):

```bash
python -m venv .venv

./.venv/bin/pip install deephaven_coreplus_client==VAR::COREPLUS_DHE_VERSION
```

Only certified builds are published to PyPi. If you are using a pre-release or candidate build, your version may not be available. In that case, you must install the package using the wheel from your Deephaven Core+ installation.

To use the client in Jupyter, also install [jupyterlab](https://pypi.org/project/jupyterlab/) and [deephaven-ipywidgets](https://pypi.org/project/deephaven-ipywidgets/):

```bash
python -m venv .venv

./.venv/bin/pip install "deephaven-ipywidgets[client]" jupyterlab deephaven_coreplus_client-VAR::COREPLUS_DHE_VERSION-py3-none-any.whl
```

Then activate your venv:

```bash
source .venv/bin/activate
```

For a list of Enterprise Python client requirements, see the file `/usr/illumon/coreplus/latest/py/resources/frozen-requirements-client-VAR::COREPLUS_DHE_VERSION.txt` on your Enterprise installation.

## Create a session

The first and most important step when using the Python client is to create a session. A session is a connection to the Deephaven server that allows you to authenticate with the server, create tables, PQs, and more. A `SessionManager` creates a session. It requires one of the following two things to connect to the server:

- A URL to a `connection.json` file
- A JSON object with the connection details

All Deephaven servers expose a `connection.json` file. Connecting to a server via this file is simple:

```python
from deephaven_enterprise.client.session_manager import SessionManager

connection_json = "https://deephaven-host:8000/iris/connection.json"

session_mgr = SessionManager(connection_json)
```

> [!NOTE]
> This example uses port `8000`. Your server may use a different port. Typically, the port is `8123` for servers _without_ Envoy and `8000` for servers _with_ Envoy.

## Authenticate

You should already have login credentials for the server. Use them to authenticate with the server:

```python
session_mgr.password("username", "password")
```

Now that you're logged in, you can start doing things with Deephaven!

## Use the client

### Create a new worker

A common use case for the client is to create a new worker and run queries on it. The following code connects to a new unnamed worker with 4GB of memory:

```python
session = session_mgr.connect_to_new_worker(name=None, heap_size_gb=4.0)
```

![Log readout after running the above query](../../assets/quickstart/pyclient/connect.png)

### Run queries on the worker

The Python client has some built-in methods, like ones to consume static and ticking tables:

```python
static_table = session.historical_table(
    namespace="LearnDeephaven", table_name="StockTrades"
)

ticking_table = session.live_table(
    namespace="DbInternal", table_name="ProcessEventLog"
).tail(100)

print(f"Static table: {static_table}\n")
print(f"Ticking table: {ticking_table}")
```

![Log readout from the above print statements](../../assets/quickstart/pyclient/first-query.png)

The client can also run queries on the server:

```python
my_query = "\n".join(
    [
        "from deephaven import time_table",
        "from deephaven import empty_table",
        "static_table = db.historical_table(namespace='LearnDeephaven', table_name='StockTrades')",
        "ticking_table = db.live_table(namespace='DbInternal', table_name='ProcessEventLog').tail(100)",
    ]
)

session.run_script(my_query)
```

Workers should be closed once you're done with them:

```python
session.close()
```

### Connect to a PQ

Instead of creating a new temporary worker, you can also connect to an existing PQ:

```python
pq_session = session_mgr.connect_to_persistent_query("MyPersistentQuery")

my_ticking_table = pq_session.open_table("ticking_table")
print(f"Ticking table has {my_ticking_table.size} rows.")

pq_session.close()
```

### Close the `SessionManager` object

Once your Python code is done performing operations on PQs, close the `SessionManager` object:

```python
session_mgr.close()
```

## Jupyter

You can also use the Python client from Jupyter. To do so, follow all of the same steps presented in [installation](#installation), but be sure also to install the [`deephaven-ipywidgets`](https://pypi.org/project/deephaven-ipywidgets/) package, which allows you to display tables and other Deephaven objects in Jupyter.

## Related documentation

- [Code Studio](../../interfaces/web/code-studio.md)
- [Creating dashboards](../create-dashboard/by-hand.md)
- [Ingesting data](../data-in/streaming-kafka.md)
- [Python client guide](../../clients/python/coreplus-python-client.md)
- [Writing queries](../develop-query/deephaven-ide.md)
- [Pydoc](https://docs.deephaven.io/pycoreplus/2026.01/client/code/deephaven_enterprise.client.session_manager.html#module-deephaven_enterprise.client.session_manager)