---
sidebar_label: Install custom Python virtual environments
---

If [`DH_COREPLUS_PYTHON`](../installation/cluster-config-guide.md#dh_coreplus_python) is set to a Python executable or short version (such as `3.12`) in your [`cluster.cnf`](../installation/cluster-config-guide.md) file, then a [default Python virtual environment](../../user-guide/python-environment.md) is configured for Core+ workers. You can also create alternative Python virtual environments and assign them to your own custom worker kinds.

To install a Python environment for the Core+ worker, you must create a virtual environment and configure it properly for the installed Community version. Deephaven recommends placing them in `/usr/illumon/coreplus/venv/`.

In the following example, we create a default virtual environment in the `/usr/illumon/coreplus/venv/VAR::COREPLUS_DHC_VERSION-custom` directory. The `requirements.txt` file provides a list of packages and versions that Deephaven has tested with this distribution. You should use it as a starting point for adding, removing, or replacing packages. Deephaven does not test integrations with package versions other than those listed in `requirements.txt`.

In addition to the `requirements.txt` file (which references packages available via `pip`), you must also install the Deephaven Core+ worker wheel. It is recommended that you also install the Deephaven Core+ client wheel.

> [!NOTE]
> In the snippets below, be sure to change the path to match your Core+ install and select the proper Community `pip` package version.

The following snippet installs a custom Python virtual environment with `pip`:

```bash
# Replace the paths below where you wish to a) install the virtual environment,
# b) take the requirements.txt file (which specifies Python dependencies) from,
# and c) source the appropriate Enterprise Core+ wheels.
#
# While not required, Deephaven recommends that you install the virtual environment
# inside the Core+ package directory for each specific version.
venvPath=/usr/illumon/coreplus/venv/VAR::COREPLUS_DHC_VERSION-custom
sudo -u irisadmin python3.10 -m venv $venvPath
sudo -u irisadmin /bin/bash -c "source $venvPath/bin/activate && \
pip3.10 install -r /usr/illumon/coreplus/latest/py/resources/requirements.txt && \
pip3.10 install /usr/illumon/coreplus/latest/py/wheel/deephaven_coreplus_worker-VAR::COREPLUS_DHE_VERSION-py3-none-any.whl && \
pip3.10 install /usr/illumon/coreplus/latest/py/wheel/deephaven_coreplus_client-VAR::COREPLUS_DHE_VERSION-py3-none-any.whl"
```

If, instead, you prefer to use `conda`, refer to the snippet below to install a custom Python virtual environment:

```bash
export PYTHONNOUSERSITE=True
conda create --prefix /usr/illumon/coreplus/venv/corePlusConda python=3.10
conda activate /usr/illumon/coreplus/venv/corePlusConda
/usr/illumon/coreplus/venv/corePlusConda/bin/pip3 install -r /usr/illumon/coreplus/latest/py/resources/requirements.txt
/usr/illumon/coreplus/venv/corePlusConda/bin/pip3 install /usr/illumon/coreplus/latest/py/wheel/deephaven_coreplus_worker-VAR::COREPLUS_DHE_VERSION-py3-none-any.whl
/usr/illumon/coreplus/venv/corePlusConda/bin/pip3 install /usr/illumon/coreplus/latest/py/wheel/deephaven_coreplus_client-VAR::COREPLUS_DHE_VERSION-py3-none-any.whl
```

You must create the virtual environment on each query server.

## Disable temporary virtual environments

By default, users can create temporary (ephemeral) virtual environments when starting a [Code Studio](../../interfaces/web/code-studio.md#show-advanced) session or configuring a [Persistent Query](../../query-management/ui-queries.md). This allows them to install additional Python packages at startup.

To prevent users from creating temporary virtual environments for a worker kind, set the per-kind property in `iris-environment.prop`:

```properties
WorkerKind.DeephavenCommunity.ephemeralVenv.enabled=false
```

If not set, the default is `true`.

> [!NOTE]
> After changing this property, users must reload their browser for the UI to reflect the new setting. Until they reload, the UI will not show the warning banner — but the controller will still block ephemeral venv creation server-side, which may cause unexpected failures for queries that request a temporary virtual environment.

When ephemeral virtual environments are disabled for a worker kind:

- In the Code Studio and Query Monitor UIs, the **Python Environment** section is hidden for new configurations. For existing configurations that already have `ephemeral_venv=true`, the temporary virtual environment control remains visible but disabled, with a warning banner explaining the restriction.
- Any existing query configuration that requests a temporary virtual environment will log a warning but still proceed — the controller will silently force `ephemeral_venv` to `false` when creating workers.
- Worker creation requests that include ephemeral venv settings are sanitized by the controller so workers are created without ephemeral virtual environments.

## Related documentation

- [Python environment](../../user-guide/python-environment.md)
- [Code Studio](../../interfaces/web/code-studio.md)
- [Query Monitor](../../interfaces/web/query-monitor.md)
- [`venv` Pydoc](https://docs.deephaven.io/pycoreplus/2026.01/worker/autoapi/deephaven_enterprise/venv/index.html#module-deephaven_enterprise.venv)