Installation

ATOM runs on AMD Instinct GPUs via ROCm. This page covers system requirements, installation, and environment setup.

Requirements

  • Python 3.10 to 3.12

  • ROCm 6.0 or later

  • PyTorch with ROCm support

  • AMD Instinct GPU (MI200, MI300, or MI350 series recommended)

If ROCm is not yet installed, follow the ROCm installation guide before continuing.

Verify your ROCm installation before proceeding:

amd-smi
rocminfo | grep gfx

Installation methods

Choose the method that fits your workflow:

  • From source — use this when you need to modify ATOM or track the latest development changes.

  • Docker — use this for a pre-configured environment with ROCm, PyTorch, and all dependencies already installed. Recommended for most deployments.

From source

git clone --recursive https://github.com/ROCm/ATOM.git
cd ATOM
pip install -r requirements.txt
pip install -e .

The --recursive flag is required because ATOM depends on AITER as a submodule.

Docker

The pre-built image includes ROCm, PyTorch, and all ATOM dependencies.

docker pull rocm/atom:latest

docker run --device=/dev/kfd --device=/dev/dri \
           --group-add video --ipc=host \
           -it rocm/atom:latest

--device=/dev/kfd and --device=/dev/dri expose the GPU to the container. --ipc=host is required for multi-GPU workloads that use shared memory between processes.

Environment variables

Set these variables in your shell before building or starting the server:

# ROCm installation path (default if installed via package manager)
export ROCM_PATH=/opt/rocm

# Target GPU architectures — include every architecture you intend to run on
# gfx90a = MI250X, gfx942 = MI300X, gfx950 = MI355X
export GPU_ARCHS="gfx90a;gfx942"

# Suppress AITER kernel log flooding during server startup
export AITER_LOG_LEVEL=WARNING

GPU_ARCHS controls which GPU targets are compiled. Omitting an architecture means ATOM will not run on that GPU. See ATOM Environment Variables for a full list of ATOM_* runtime variables.

Verify the installation

Run the following to confirm ATOM imported correctly and ROCm is accessible:

import atom
import torch

print("ATOM modules available:")
print(f"  - LLMEngine: {hasattr(atom, 'LLMEngine')}")
print(f"  - SamplingParams: {hasattr(atom, 'SamplingParams')}")

print(f"\nPyTorch version: {torch.__version__}")
print(f"ROCm available: {torch.cuda.is_available()}")
print(f"ROCm version: {torch.version.hip if hasattr(torch.version, 'hip') else 'N/A'}")

A successful installation prints True for both LLMEngine and SamplingParams, and shows a ROCm version string rather than N/A.

Troubleshooting

ImportError: No module named ‘atom’

The ATOM package is not on PYTHONPATH. If you installed from source with pip install -e ., confirm you are in the same virtual environment. Also ensure ROCm libraries are on the library path:

export LD_LIBRARY_PATH=/opt/rocm/lib:$LD_LIBRARY_PATH
RuntimeError: No AMD GPU found

The GPU is not visible to the process. Check that amd-smi lists your device and that the ROCm kernel modules are loaded:

amd-smi
rocminfo | grep gfx

In Docker, confirm you passed --device=/dev/kfd --device=/dev/dri when starting the container.

AITER log flooding on startup

AITER prints kernel selection logs by default. Suppress them with:

export AITER_LOG_LEVEL=WARNING