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

# Linux Machine Deployment Setup

> Install Kumo and prepare your Linux machine to connect data

Install Kumo in a dedicated Python environment, check GPU access, and configure local working storage.
After setup, 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](/sdgm/kumo-engine/get-started-with-kumo-engine/gpu-sizing) when choosing compute.

Verify that the GPU is visible:

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

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

If you install PyTorch separately or use a private package index, select a CUDA build compatible with your Kumo version and NVIDIA driver.
Follow the [PyTorch installation instructions](https://pytorch.org/get-started/previous-versions/) for the CUDA package index; the Intel XPU index is for Intel GPUs.

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

| Installation                     | Command                                 |
| -------------------------------- | --------------------------------------- |
| Base Kumo Engine for local files | `pip install kumo-engine`               |
| Amazon S3                        | `pip install "kumo-engine[s3]"`         |
| Google Cloud Storage             | `pip install "kumo-engine[gcs]"`        |
| BigQuery                         | `pip install "kumo-engine[bigquery]"`   |
| Snowflake                        | `pip install "kumo-engine[snowflake]"`  |
| Databricks                       | `pip install "kumo-engine[databricks]"` |

**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](/sdgm/kumo-engine/get-started-with-kumo-engine/prerequisites).

To connect to both Snowflake and Databricks, install both extras:

```bash
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 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 and results.

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

```bash
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 this check 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.

```python
import os
from pathlib import Path
from tempfile import TemporaryFile

import kumo.engine
import torch
import torch_geometric

if torch.version.cuda is None:
    raise RuntimeError("PyTorch has no CUDA support. Install a compatible CUDA build of PyTorch.")
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)
```

The output should show 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](/sdgm/kumo-engine/user-code-guide/connect-your-data-linux).