macOS Setup | NVIDIA Kumo

Install Kumo Engine on your Apple silicon Mac, verify Apple 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 macOS 14 or later on Apple silicon and an ARM64 Python interpreter. Intel Macs and Python running through Rosetta are not supported. Install Python 3.12 from Python.org if it is not already available. In Terminal, check the interpreter architecture:

python3.12 -c 'import platform; print(platform.machine())'

The result must be arm64. If it prints x86_64, use a native ARM64 interpreter and terminal session before creating the virtual environment. Kumo can use the Apple GPU through PyTorch’s Metal Performance Shaders (MPS) backend or run on CPU. CUDA is not used on macOS.

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.

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; 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 = "mps" if torch.backends.mps.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__, "MPS available:", torch.backends.mps.is_available())
print("PyG:", torch_geometric.__version__)
print("Device:", device)
print("Kumo working directory:", scratch)

The output lists package versions, the selected device (mps or cpu), and your working directory. If you expected Apple GPU execution but see cpu, check your ARM64 interpreter and PyTorch MPS availability. 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="mps" when creating a trainer to select CPU or Apple GPU 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.