> This page is for Kumo Engine.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Windows (WSL2) Setup

> Install Kumo Engine inside Windows Subsystem for Linux 2 (WSL2), verify NVIDIA GPU or CPU execution, and prepare local working storage.

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](/sdgm/kumo-engine/get-started-with-kumo-engine/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](https://learn.microsoft.com/en-us/windows/wsl/install) for Windows requirements.

In **PowerShell as administrator**, install Ubuntu and update WSL:

```powershell
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:

```powershell
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:

```bash
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](https://docs.nvidia.com/cuda/wsl-user-guide/index.html) 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:

```bash
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](/sdgm/kumo-engine/get-started-with-kumo-engine/prerequisites#python-and-package-access) 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:

```bash
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](/sdgm/kumo-engine/user-code-guide/train-a-model/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.

```python
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](/sdgm/kumo-engine/user-code-guide/connect-your-data-linux).