Linux Machine Deployment Setup

Install Kumo in a dedicated Python environment, check GPU access, and configure local working storage. After completing this guide, you can connect your data from the same environment.

Before You Begin

Prepare an Ubuntu 24.04 x86_64 machine with:

• Python 3.12, including pip and venv.
• An NVIDIA GPU with a compatible driver installed.
• Local storage mounted with write access for your user.
• Access to the Python package index and the services that hold your data.

Memory, GPU memory, and storage capacity depend on your dataset and workload. See GPU Sizing when choosing compute.

Verify that the GPU is visible:

nvidia-smi

The output should list your GPU and driver version. If the command fails or shows no GPU, resolve the machine’s driver or GPU access configuration before continuing.

Install Kumo

Create and activate a virtual environment:

python3.12 -m venv .venv
source .venv/bin/activate

Install Kumo Engine with the integration dependencies required by your data source:

Each remote connector requires its corresponding integration dependencies. If you already installed the base package, run the command for your data source in the same virtual environment to add its integration dependencies. Use the configured package index and compatible build described in Prerequisites.

To connect to both warehouses, install both extras:

pip install "kumo-engine[snowflake,databricks]"

Keep this environment active for the remaining steps and when running your Kumo scripts. The Python import name is kumo.engine.

Configure Working Storage

Kumo uses local storage for graph snapshots and the working files created during training and prediction. Choose a directory on your mounted local storage volume. Keep it separate from your source data and leave space for intermediate files as well as results.

Replace /path/to/local-storage with your mount path:

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

Confirm that the reported filesystem is your local storage volume. Ask your administrator if you are unsure which mount to use. A writable directory or an NVMe device name alone does not establish that the storage is local to the machine. Network disks and cloud block volumes are not supported as job working storage.

Local storage can be lost when a machine is stopped or replaced. Keep durable copies of any results you need to retain outside this working directory.

Verify Your Setup

Run the following in the activated environment with KUMO_SCRATCH set. It checks that Kumo imports, performs a small GPU operation, verifies a write to the working directory, 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
if not torch.cuda.is_available():
    raise RuntimeError("No GPU is available. Check the NVIDIA driver and GPU access.")
values = torch.tensor([1.0, 2.0], device="cuda")
groups = torch.tensor([0, 0], device="cuda")
total = torch.zeros(1, device="cuda").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("GPU:", torch.cuda.get_device_name(0))
print("Kumo working directory:", scratch)

You should see the installed package versions, your GPU name, and the working directory you selected. Save this output when reporting an installation problem. If Python cannot import Kumo, PyTorch, or PyG, confirm that your virtual environment is active and that your configured package index supplied the complete build for this environment. If the storage check fails, confirm the path and your write permissions.

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 Your Data to make your source tables available to Kumo.