> 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.

# macOS Setup

> Install Kumo Engine on your Apple silicon Mac, verify Apple GPU or CPU execution, and prepare local working storage.

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](/sdgm/kumo-engine/get-started-with-kumo-engine/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](https://www.python.org/downloads/macos/) if it is not already available.
In Terminal, check the interpreter architecture:

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

```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.

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; 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 = "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](https://docs.pytorch.org/docs/stable/notes/mps.html).
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](/sdgm/kumo-engine/user-code-guide/connect-your-data-linux).