# PyCharm Remote Debugging

A

ttach PyCharm's professional debugger to your Valohai execution for interactive debugging with breakpoints, variable inspection, and step-through execution.

**What you'll accomplish:**

* Set breakpoints in PyCharm on code running in Valohai
* Inspect and modify variables in real-time
* Step through execution line-by-line on cloud infrastructure

> ⚠️ **PyCharm Professional required** - Remote debugging is only available in PyCharm Professional, not Community Edition.

***

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before starting, ensure you have:

1. **SSH access configured** - Follow [SSH Overview](/development-and-debugging/ssh-overview.md) to set up keys and firewall rules
2. **PyCharm Professional** installed
3. **SSH private key** from the SSH setup

***

### Configure PyCharm Debug Server <a href="#configure-pycharm-debug-server" id="configure-pycharm-debug-server"></a>

#### Create Debug Configuration <a href="#create-debug-configuration" id="create-debug-configuration"></a>

1. Open **Run** → **Edit Configurations**
2. Click **+** → **Python Debug Server**
3. Configure:
   * **Name:** `Valohai Remote Debug`
   * **IDE host name:** `localhost`
   * **Port:** `1234` (local port for incoming connections)
4. Click **OK**

<figure><img src="/files/gY3aSTB3UrkCSQtmLLyb" alt=""><figcaption></figcaption></figure>

#### Start Debug Server <a href="#start-debug-server" id="start-debug-server"></a>

Click the debug icon next to your new configuration. PyCharm will start listening for connections.

**Keep this running** - Your Valohai execution will connect to this server.

***

### Add pydevd-pycharm to Your Code <a href="#add-pydevd-pycharm-to-your-code" id="add-pydevd-pycharm-to-your-code"></a>

PyCharm's `pydevd-pycharm` package enables remote debugging. Install it and add connection logic to your training script.

#### Python Code <a href="#python-code" id="python-code"></a>

```python
import pydevd_pycharm
import numpy as np
import time

# Try connecting to PyCharm debug server
connected = False

while not connected:
    try:
        # Connect to debug server via SSH tunnel
        # Port 1234 is the container-side port (mapped through SSH)
        pydevd_pycharm.settrace(
            "localhost",
            port=1234,
            stdoutToServer=True,
            stderrToServer=True,
        )
        connected = True
    except Exception:
        print("Waiting for PyCharm debug connection...")
        time.sleep(10)

# Your training code runs after debugger connects
for x in range(1, 20):
    print(f"Doing computation {x}")
    data = np.random.random((50, 50))
    sum = np.sum(data)
    time.sleep(2)
```

**Key points:**

* `settrace('localhost', port=1234)` - Connects to PyCharm through SSH tunnel
* Retry loop ensures connection even if PyCharm isn't ready yet
* `stdoutToServer=True` - Routes print statements to PyCharm console

#### valohai.yaml <a href="#valohaiyaml" id="valohaiyaml"></a>

```yaml
- step:
    name: train
    image: python:3.9
    command:
      - pip install numpy pydevd-pycharm~=<PYCHARM-VERSION>
      - python train.py
```

**Replace `<PYCHARM-VERSION>`** with your PyCharm version (e.g., `241.14494.240` for PyCharm 2024.1). Find your version in **Help** → **About**.

> 💡 *The execution will loop at `settrace()` until PyCharm connects. This keeps it running without needing `sleep` commands.*

***

### Start Execution with SSH <a href="#start-execution-with-ssh" id="start-execution-with-ssh"></a>

Launch your execution with SSH debugging enabled:

**Web UI:**

1. Enable **Run with SSH**
2. Paste public key or auto-generate
3. Start execution

**Command Line:**

```shell
vh exec run --adhoc --debug-key-file=/path/to/key.pub --debug-port 2222 train
```

**Wait for the IP address** in execution logs:

```
SSH connection available at: 52.214.159.193:2222
```

***

### Connect PyCharm to Execution <a href="#connect-pycharm-to-execution" id="connect-pycharm-to-execution"></a>

#### Establish Reverse SSH Tunnel <a href="#establish-reverse-ssh-tunnel" id="establish-reverse-ssh-tunnel"></a>

PyCharm's debug server listens locally, so we need a **reverse tunnel** that lets the remote execution connect back to your machine.

```shell
ssh -i /path/to/private-key <IP-FROM-LOGS> -p 2222 -R 1234:localhost:1234 -t /bin/bash
```

**What this does:**

* Connects to Valohai execution via SSH
* Forwards container port 1234 → your local port 1234 (reverse tunnel)
* Opens the bash shell in the container

> 💡 *Keep this terminal window open while debugging.*

#### Handle Path Mapping <a href="#handle-path-mapping" id="handle-path-mapping"></a>

When PyCharm first connects, you may see:

<figure><img src="/files/yvYvckLwa3bxVnkXs0hq" alt=""><figcaption></figcaption></figure>

**Solution:** Click **Auto-detect** to map container paths to your local project.

#### Verify Connection <a href="#verify-connection" id="verify-connection"></a>

Check the PyCharm **Debugger** console - you should see:

```
Connected to pydev debugger (build 241.14494.240)
```

Your code will pause at the next breakpoint or line.

***

### Debug Your Code <a href="#debug-your-code" id="debug-your-code"></a>

Once connected, you can:

* **Set breakpoints** - Click left of line numbers in editor
* **Inspect variables** - View in Variables panel or hover in editor
* **Evaluate expressions** - Use Console to run Python during breakpoint
* **Step through code** - F8 (step over), F7 (step into), Shift+F8 (step out)
* **Modify variables** - Right-click variable → Set Value

Click the **Resume** button (green arrow) to start execution after connection.

***

### Common Issues <a href="#common-issues" id="common-issues"></a>

**PyCharm can't establish connection?**

* Verify debug server is running in PyCharm
* Ensure SSH tunnel is active (check terminal)
* Confirm execution hasn't timed out

**Version mismatch error?**

* Update `pydevd-pycharm~=<VERSION>` in valohai.yaml to match your PyCharm version
* Find version in **Help** → **About** → copy build number

**Path mapping not working?**

* Click **Auto-detect** when prompted
* Manually add mapping: Local path → `/valohai/repository`

**Execution exits before connecting?**

* The retry loop should prevent this
* Check execution logs for `pip install` errors
* Verify PyCharm debug server started before execution

***

### Next Steps <a href="#next-steps" id="next-steps"></a>

* [VS Code Remote Debugging](/development-and-debugging/vs-code-remote-debugging.md) - Alternative IDE debugging
* [SSH Overview](/installation-and-setup/advanced-topics/configure-ssh-access.md) - Learn about direct SSH access and tunneling


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/development-and-debugging/pycharm-remote-debugging.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.