Getting Started Windows

Getting Started — Windows

OncoLearn on Windows requires WSL2 (Windows Subsystem for Linux). Native Windows is not supported.

Tested configuration: Only WSL2 with an AMD GPU (ROCm via prod-rocm-wsl) has been tested. If you run into issues on another configuration, please open a GitHub issue.

---

Prerequisites

• Windows 10 or Windows 11
• WSL2 with Ubuntu 22.04 or later
• AMD GPU (WSL-AMD tested) or CPU-only fallback
• Docker Desktop with WSL2 backend enabled

All commands below are run inside a WSL2 terminal unless stated otherwise.

---

Installation

1. Install ROCm (AMD GPU only)

ROCm must be installed on the WSL2 host regardless of whether you use Docker or run directly. The Docker containers mount ROCm libraries from the host at runtime.

Follow the official guide: ROCm for WSL2 — AMD Radeon/Ryzen install guide

2. Clone the repository

git clone --recurse-submodules https://github.com/collaborativebioinformatics/OncoLearn.git OncoLearn
cd OncoLearn

If you forgot --recurse-submodules, run git submodule update --init afterwards.

---

Docker (recommended)

Docker is the recommended way to run OncoLearn on Windows/WSL2. It handles all ROCm library paths automatically and avoids manual dependency management.

1. Get the images

You need two images: the dev image (for data download) and the prod image (for training). Either build locally or pull from GHCR — see the Docker guide for both options. To build locally:

# Dev image (for data download)
docker compose --profile dev-rocm-wsl build dev-rocm-wsl

# Prod image (for training)
docker compose --profile prod-rocm-wsl build prod-rocm-wsl

2. Download data

Data downloads require the dev image (the prod image is training-only). See the CLI guide for all available options.

# miRNA expression
docker compose --profile dev-rocm-wsl run --rm dev-rocm-wsl \
  oncolearn xena download --cohorts BRCA --category mirna_seq --unzip --output ./data/xenabrowser

# PAM50 subtype labels
docker compose --profile dev-rocm-wsl run --rm dev-rocm-wsl \
  oncolearn xena download --cohorts BRCA --category clinical --unzip --output ./data/xenabrowser

3. Run training

# Tabular only (faster, no images required)
docker compose --profile prod-rocm-wsl run --rm prod-rocm-wsl \
  python -m oncolearn.trainer --variant v2_no_imaging --epochs 10 --batch_size 8

# Full multimodal
docker compose --profile prod-rocm-wsl run --rm prod-rocm-wsl \
  python -m oncolearn.trainer --variant v1_imaging --epochs 10 --batch_size 8

See the Docker guide for all services, volume mounts, and further details.

---

Without Docker (manual setup)

If you prefer to run outside of Docker, install Python dependencies with uv:

1. Install with uv

# CPU-only (data download and EDA)
uv sync --extra cpu --extra multimodal

# ROCm (AMD, WSL2 — only tested configuration on Windows)
uv sync --extra rocm --extra multimodal

2. Run training

# Tabular only
python -m oncolearn.trainer --variant v2_no_imaging

# Full multimodal
python -m oncolearn.trainer --variant v1_imaging

---

Notes

• WSL-AMD only tested: Other GPU configurations (NVIDIA, CPU) are untested on Windows. They may work but are unsupported.
• Issues: If something doesn't work, please open a GitHub issue with your WSL version (wsl --version), GPU model, and the full error output.