Windows (WSL2) Setup | NVIDIA Kumo

Install Kumo Engine inside Windows Subsystem for Linux 2 (WSL2), verify NVIDIA GPU or CPU execution, and prepare local working storage. For production workloads, use a compatible NVIDIA GPU. CPU execution is suitable for small jobs.

Before You Begin

Prepare local SSD storage and access to PyPI. These steps use Python 3.12; see Prerequisites for the support matrix.

Use an x86_64 Windows machine with WSL2 and Ubuntu 24.04. Kumo runs inside Linux in WSL2; native Windows Python and WSL1 are not supported. Follow Microsoft’s WSL installation instructions for Windows requirements.

In PowerShell as administrator, install Ubuntu and update WSL:

wsl --install -d Ubuntu-24.04
wsl --update

Restart if prompted, launch Ubuntu, and complete its Linux user setup. In PowerShell, check the distribution version:

wsl --list --verbose

Confirm that Ubuntu shows VERSION 2. If it shows 1, convert it with wsl --set-version Ubuntu-24.04 2.

Run all remaining shell and Python commands inside Ubuntu, including package installation:

sudo apt update
sudo apt install python3.12-venv python3-pip
uname -m

The architecture must be x86_64. For NVIDIA GPU execution, follow CUDA on WSL and install the NVIDIA driver on Windows, not a Linux display driver inside WSL. Confirm GPU visibility with nvidia-smi inside Ubuntu. Without a GPU, use CPU execution for small jobs.

Install Kumo

Create a project directory on local SSD storage, then create and activate a virtual environment inside it:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install kumo-engine

The base package reads local CSV and Parquet files. Add the integration dependencies for your data source in this same environment when connecting a remote source. Keep the environment active for the remaining steps and when running your Kumo scripts.

Configure Working Storage

Kumo uses local SSD storage for graph snapshots and working files created during training and prediction. Choose a writable directory on your local SSD, separate from source data, with space for intermediate files and results. Network disks and cloud block volumes are not supported as job working storage.

Use the Linux filesystem, such as a directory under your Linux home, with the WSL virtual disk stored on a local SSD. Avoid Windows-mounted paths such as /mnt/c for working files.

Replace /path/to/local-storage with your chosen directory:

export KUMO_SCRATCH=/path/to/local-storage/kumo-scratch
mkdir -p "$KUMO_SCRATCH"
df -h "$KUMO_SCRATCH"

Confirm the backing storage and available capacity before running a job. A writable path alone does not establish that it is on local SSD storage. Keep retained model bundles and outputs separate from scratch and back them up; removing a WSL distribution or replacing a machine can remove its local files. See Publish and Retrieve Models.

Verify Your Setup

Run the following in the activated environment with KUMO_SCRATCH set. It checks imports, performs a small operation on an available device, verifies a write to scratch, and configures that directory for the current Python process.

import os
from pathlib import Path
from tempfile import TemporaryFile
import kumo.engine
import torch
import torch_geometric
device = "cuda" if torch.cuda.is_available() else "cpu"
values = torch.tensor([1.0, 2.0], device=device)
groups = torch.tensor([0, 0], device=device)
total = torch.zeros(1, device=device).scatter_add_(0, groups, values)
assert total.item() == 3.0
scratch = Path(os.environ["KUMO_SCRATCH"]).expanduser().resolve()
scratch.mkdir(parents=True, exist_ok=True)
with TemporaryFile(dir=scratch) as probe:
    probe.write(b"kumo storage check")
    probe.flush()
kumo.engine.configure(scratch_dir=scratch)
print("Kumo:", kumo.engine.__version__)
print("PyTorch:", torch.__version__, "CUDA:", torch.version.cuda)
print("PyG:", torch_geometric.__version__)
print("Device:", device)
print("Kumo working directory:", scratch)

The output lists package versions, the selected device (cuda or cpu), and your working directory. If you expected NVIDIA GPU execution but see cpu, check the Windows NVIDIA driver and GPU access inside WSL2. If imports fail, confirm that your virtual environment is active and the package installation completed. If the storage check fails, confirm the path and write permissions. This check verifies basic device execution and scratch access; it does not train a model or establish that your dataset fits.

Kumo’s Trainer defaults to accelerator="auto". Pass accelerator="cpu" or accelerator="gpu" when creating a trainer to select CPU or NVIDIA CUDA execution explicitly. The selection applies to training and prediction.

In each new shell, activate your virtual environment and set KUMO_SCRATCH again. In each script, call kumo.engine.configure(scratch_dir=...) before creating graphs or trainers. Configuration applies to that Python process; it does not persist between runs.

Next Step

Continue to Connect Data from Local Python.