Setup Guide

June 17, 2026 · View on GitHub

System Requirements
Installation
Downloading Checkpoints
Troubleshooting

System Requirements

NVIDIA GPUs with Ampere architecture (RTX 30 Series, A100) or newer
NVIDIA driver >=570.124.06 compatible with CUDA 12.8.1
Linux x86-64
glibc>=2.35 (e.g Ubuntu >=22.04)

Installation

sudo apt install git-lfs
git lfs install

Clone the repository:

git clone git@github.com:nv-tlabs/Gamma-World.git
cd Gamma-World
git lfs pull

Install one of the following environments:

Virtual Environment

Install system dependencies:

sudo apt update && sudo apt -y install curl ffmpeg libx11-dev tree wget

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

Install the package into a new environment:

uv python install
uv sync --extra=cu128
source .venv/bin/activate

Or, install the package into the active environment (e.g. conda):

uv sync --extra=cu128 --active --inexact

CUDA Variants:

CUDA Version	Arguments	Notes
CUDA 12.8	`--extra cu128`	NVIDIA Driver
CUDA 13.0	`--extra cu130`	NVIDIA Driver

For DGX Spark and Jetson AGX, you must use CUDA 13.0.

Docker Container

Please make sure you have access to Docker on your machine and the NVIDIA Container Toolkit is installed.

Build the container:

# Ampere - Hopper
image_tag=$(docker build -f Dockerfile -q .)
# Blackwell
image_tag=$(docker build -f docker/nightly.Dockerfile -q .)

Run the container:

docker run -it --runtime=nvidia --ipc=host --rm -v .:/workspace -v /workspace/.venv -v /root/.cache:/root/.cache -e HF_TOKEN="$HF_TOKEN" $image_tag

Optional arguments:

--ipc=host: Use host system's shared memory, since parallel torchrun consumes a large amount of shared memory. If not allowed by security policy, increase --shm-size (documentation).
-v /root/.cache:/root/.cache: Mount host cache to avoid re-downloading cache entries.
-e HF_TOKEN="$HF_TOKEN": Set Hugging Face token to avoid re-authenticating.

If you get docker: Error response from daemon: unknown or invalid runtime name: nvidia, you need to configure docker:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Downloading Checkpoints

Gamma-World pulls three sets of weights, all hosted on Hugging Face:

Component	Hugging Face repo	Contents
World-model networks	`chijw/Gamma-World`	`bidirectional/`, `causal/`, `causal-few-step/` network `model.safetensors`
VAE tokenizer	`chijw/Gamma-World`	`tokenizer.pth`
Text encoder (VLM)	`nvidia/Cosmos-Reason1-7B`	encodes the text prompt

Get a Hugging Face Access Token with Read permission.
Install the Hugging Face CLI: uv tool install -U "huggingface_hub[cli]".
Login: hf auth login.
Accept the NVIDIA Open Model License on the Cosmos-Reason1-7B page.

The VAE and the text encoder download automatically on first run — --vae and --text-encoder default to their hf:// URIs. The network is selected with --checkpoint hf://chijw/Gamma-World/<mode>/model.safetensors. Set HF_HOME to change where they are cached.

For an offline node, pre-download everything and pass local paths instead:

hf download chijw/Gamma-World        --local-dir ./checkpoints/Gamma-World
hf download nvidia/Cosmos-Reason1-7B --local-dir ./checkpoints/Cosmos-Reason1-7B

Then run with --checkpoint ./checkpoints/Gamma-World/causal-few-step/model.safetensors --vae ./checkpoints/Gamma-World/tokenizer.pth --text-encoder ./checkpoints/Cosmos-Reason1-7B (see Inference).

Troubleshooting

These errors surface when running python scripts/check_environment.py on a host without CUDA installed system-wide (i.e. relying on the pip-installed nvidia-*-cu12 wheels that PyTorch pulls in).

`ldconfig -p | grep 'libnvrtc'` returns non-zero

File ".../transformer_engine/common/__init__.py", line 111, in _load_nvrtc
    libs = subprocess.check_output("ldconfig -p | grep 'libnvrtc'", shell=True)
subprocess.CalledProcessError: Command 'ldconfig -p | grep 'libnvrtc'' returned non-zero exit status 1.

transformer_engine._load_nvrtc() first globs $CUDA_HOME/**/libnvrtc.so* and only falls back to ldconfig if CUDA_HOME is unset. Point CUDA_HOME at the venv's bundled CUDA libs:

export CUDA_HOME="$VIRTUAL_ENV/lib/python3.10/site-packages/nvidia"

`libcublas.so.12: cannot open shared object file`

OSError: libcublas.so.12: cannot open shared object file: No such file or directory

The transformer_engine native .so depends on libcublas, libcudnn, libnvJitLink, etc. at dlopen() time. Add every nvidia/*/lib directory in the venv to LD_LIBRARY_PATH:

export LD_LIBRARY_PATH="$(find $VIRTUAL_ENV/lib/python3.10/site-packages/nvidia -maxdepth 3 -type d -name lib | paste -sd:)${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"

`GLIBC_2.34' not found` from `~/.triton/cache/.../cuda_utils.so`

ImportError: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found
  (required by /home/<user>/.triton/cache/.../cuda_utils.so)

~/.triton/cache contains a cuda_utils.so compiled against a newer glibc (e.g. from a previous run inside a container with Ubuntu 22+). On a host with older glibc the cached object is ABI-incompatible. Triton regenerates the cache on demand, so the fix is to drop it:

rm -rf ~/.triton
# Optional: redirect future Triton compilation cache off $HOME
export TRITON_CACHE_DIR=/path/to/triton_cache

Note: this host must still meet the glibc requirement in System Requirements for the recompiled cache to load.