Debug Python code in Deephaven
Deephaven supports debugging with several IDEs, whether you run it from Docker, from pip, or from source. This section shows how to debug Python code running in Deephaven from an external IDE, so you can step through code, inspect variables, and find problems.
How debugging works with Deephaven
The Deephaven web IDE does not have a built-in debugger. To debug Python scripts and user-defined functions, you need an external IDE.
Setting up a debugger depends on where the Deephaven engine runs. If it runs inside the Python process your IDE launches, the IDE's built-in debugger works locally. If it runs in a separate server process, you debug remotely. Where the engine runs depends on how you install Deephaven:
- Docker: The Docker installation runs the server in a container, separate from your IDE, so you debug remotely.
- Pip installation: How you start the server decides how you debug. A Python script that starts the server with the
deephaven-serverpackage from a pip installation runs the engine inside the Python process your IDE launches, so you debug locally. A server you start from a terminal withdeephaven serverand use from the web IDE runs outside your IDE, so you debug it remotely. - Server built from source: A server built from source and started with
./gradlew server-jetty-app:runruns the engine in its own process, separate from your IDE, so you debug remotely. - Embedded server built from source: This is the same
deephaven-serverpackage that pip installs, built as a wheel from a localdeephaven-coreclone. A script that starts it runs the engine inside the Python process your IDE launches, so you debug locally.
For local debugging, the guides in this section use the built-in debugger in PyCharm (free or Pro) or VS Code. For remote debugging, they use the remote debugging server in PyCharm Pro, the paid tier of PyCharm.
The PyCharm and VS Code debuggers in these guides step through Python code only. To step into Deephaven's Java engine, attach a JVM debugger such as IntelliJ IDEA. The source build guide and the embedded server guide show how.
Note
PyCharm 2025.1 and later ship as a single product, with free features and PyCharm Pro subscription features. Earlier releases shipped as two editions, PyCharm Community (free) and PyCharm Professional. If you use PyCharm Community 2025.2, the last standalone free release, follow the PyCharm (free) row of the table below.
Use PyCharm 2024 or later. Debugging Deephaven with PyCharm 2023 has known problems. Use VS Code 1.94 or later.
Debugging support by installation method
The following table shows debugging support for different Deephaven installation methods:
| Debugger | Docker | Pip installation | Server built from source | Embedded server built from source |
|---|---|---|---|---|
| PyCharm (free) | ❌ | ✅ | ❌ | ✅ |
| PyCharm Pro (paid) | ✅ | ✅ | ✅ | ✅ |
| VS Code | — | ✅ | — | — |
In the table:
- A check mark means that a guide in this section covers that IDE for that installation method.
- A cross means that the guide for that installation method uses PyCharm's remote debugging server, a PyCharm Pro feature, so the free tier can't follow it.
- A dash means that no guide in this section covers that IDE for that installation method.
On Windows, the pip and embedded server guides set up PyCharm with a WSL interpreter, which requires PyCharm Pro. The PyCharm (free) check marks apply to macOS and Linux.
Getting started
Choose the guide below that matches how you install and run Deephaven. Each guide shows you how to set up a debugger for the supported IDEs.
Deephaven run from Docker
Use PyCharm Pro's remote debugging server to debug Deephaven inside the container.
Deephaven installed with pip
Use PyCharm (free or Pro) or VS Code to debug scripts that run in pip-installed Deephaven. To debug a server started with deephaven server, the guide uses PyCharm Pro.
After setup, see Common problems for Deephaven-specific debugging issues. For general debugger usage, refer to your IDE's debugging documentation.
Related documentation
- Debug Docker-run Deephaven with PyCharm
- Debug pip-installed Deephaven
- Debug built-from-source Deephaven with PyCharm
- Debug an embedded Deephaven server with PyCharm
- Common problems when debugging Deephaven
- Install Deephaven with Docker
- Install Deephaven with pip
- Build and run Deephaven from source
- Python functions in query strings