Installation¶
Use the hosted Studio without installation, or run OpenDPD 2.4.1 locally. Python 3.12 is the recommended starting point; the compute suite also covers 3.10–3.13.
Install uv¶
macOS / Linux:
Windows PowerShell:
Open a new terminal so uv is on PATH. See the official uv installer for package-manager alternatives.
Create your project environment¶
These commands work on macOS, Linux and Windows; activation is unnecessary because the environment is named explicitly.
mkdir opendpd-lab
cd opendpd-lab
uv venv --python 3.12
uv pip install --python .venv "opendpd==2.4.1" --torch-backend=auto
uv run --no-project --python .venv opendpd doctor
uv run --no-project --python .venv opendpd gui
The package installs PyTorch, the API server, the prebuilt Studio frontend, and pywebview. The old [gui] and [desktop] extras remain compatible aliases. A released wheel does not require Node.js. Local datasets and runs persist in ~/opendpd-workspace; change this with opendpd gui --workspace PATH.
Platform and accelerator selection¶
| Platform | Native window | Compute |
|---|---|---|
| Apple Silicon macOS | pywebview installs PyObjC and uses WKWebView | PyTorch's macOS wheel includes MPS; Studio selects it when available |
| Intel macOS | WKWebView on a supported macOS/Python combination | CPU; availability of current PyTorch wheels depends on architecture/version |
| Linux | pywebview installs Qt, PyQt6 and Qt WebEngine | uv selects a compatible detected GPU backend; Studio supports CUDA/ROCm through cuda, otherwise CPU |
| Windows | pywebview installs pythonnet and uses WebView2 | uv selects CUDA with a compatible NVIDIA driver, otherwise CPU |
--torch-backend=auto is uv's hardware-aware installation option; it is not a pip feature. See uv's PyTorch guide and the PyTorch installation selector. A Python package cannot install an operating-system GPU driver, manufacture accelerator support on incompatible hardware, or guarantee every model supports every device. Intel XPU is not an OpenDPD execution target. opendpd doctor and Studio's device selector report what is actually available.
If PyTorch was already installed with an unsuitable backend, repair only that environment:
Linux still needs a graphical session and the system libraries Qt uses (typically libgl1, libegl1, libxcb-cursor0 and X11/XCB libraries on Debian/Ubuntu). Minimal distributions and containers may lack them. Windows needs the Microsoft WebView2 Runtime. See pywebview platform prerequisites. OpenDPD does not silently install system packages or disable the browser sandbox. On a headless machine, use --no-browser; --browser bypasses the native window and --window reports a missing native backend directly.
Optional Triton acceleration¶
DeltaGRU uses fused Triton kernels for supported NVIDIA CUDA configurations. Triton needs a C compiler and development headers for the Python interpreter in use. On Ubuntu with the distribution's default Python, install them with sudo apt-get install gcc python3-dev; for another Python version, use matching development headers.
Starting in 2.2.12, a missing C compiler produces one warning per layer and training continues with PyTorch on the same device. To choose the PyTorch path explicitly, set OPENDPD_DISABLE_TRITON_DELTAGRU=1 before launching Studio or the CLI. Other compiler, driver and CUDA failures still report their underlying error.
SSH or another computer¶
127.0.0.1 always refers to the computer running the browser. If OpenDPD runs on a Linux server and you browse from a Mac, establish a tunnel in a terminal on the Mac:
Replace USER@SERVER with your server login. Keep both this tunnel and the terminal running opendpd gui --no-browser --port 8765 open. Open the bootstrap URL printed by that running server in the Mac browser. If Studio chose a different port, use that port on both sides of -L. You may choose another local port if 8765 is occupied; then change only the browser URL's port to match it. Do not publish the bootstrap token.
A browser-open failure is nonfatal: Studio continues serving its URL. The launcher now explains local addresses and prints forwarding guidance when SSH is detected. Its loopback health checks bypass system HTTP proxies. The service stays bound to loopback; opening it on a LAN is unnecessary.
Troubleshooting connection refused¶
- Keep the launcher running. Closing its native window, pressing Ctrl+C, closing the terminal, or disconnecting SSH stops it.
- Use the current printed port and URL. Another machine requires the tunnel above.
- On the server, check
curl http://127.0.0.1:8765/healthz(PowerShell:Invoke-RestMethod http://127.0.0.1:8765/healthz). If this fails, inspect the launcher's terminal for a startup error and runopendpd doctorin the same environment. - If the health check works locally but the browser cannot connect, check your SSH forward or browser proxy's localhost bypass. A session-expired response is different from connection refused; reopen the current bootstrap URL to renew the session.
pip and source installations¶
Standard pip installs all Python dependencies too:
pip cannot detect your GPU driver to choose a custom PyTorch index. For acceleration, prefer the uv command above, or follow the official PyTorch selector before installing OpenDPD. Running from a source checkout also needs Git and Node.js 22.22+:
git clone https://github.com/lab-emi/OpenDPD.git
cd OpenDPD
uv venv --python 3.12
uv pip install --python .venv -e ".[dev]" --torch-backend=auto
npm --prefix frontend ci
npm --prefix frontend run build
uv run --no-project --python .venv opendpd gui
For Windows source upgrades, a fresh clone applies the versioned LF rules for Python files, keeping Arena's source integrity checks consistent. The published wheel also preserves these source bytes.
After source changes, rerun the editable install and frontend build. See Contributing and the platform support matrix.