Setup Guide

March 17, 2026 ยท View on GitHub

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)
  • Python 3.10

Installation

Install git lfs:

sudo apt install git-lfs
git lfs install

Clone the repository:

git clone git@github.com:nvidia-cosmos/<repository_name>.git
cd <repository_name>
git lfs pull

Virtual Environment

For Blackwell, you must use Docker. We are working on adding virtual environment support.

Install system dependencies:

sudo apt install curl ffmpeg tree wget

uv

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

Install the package into a new environment:

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

Hybrid Workflow (Conda + UV)

For users who prefer managing environments with Conda while leveraging the speed of UV for dependency management:

  1. Create and activate your environment:
conda create -n worldcache python=3.10 -y
conda activate worldcache
  1. Install the package and dependencies using UV into the active environment:
uv sync --extra=cu128 --active --inexact

Tip

This is often the most reliable way to maintain system-wide CUDA dependencies while keeping a localized, fast-syncing project environment.

CUDA Variants:

  • --extra=cu128: CUDA 12.8
  • --extra=cu130: 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 --gpus all --ipc=host --rm -v .:/workspace -v /workspace/.venv -v /root/.cache:/root/.cache $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.

Downloading Checkpoints

  1. Get a Hugging Face Access Token with Read permission
  2. Install Hugging Face CLI: uv tool install -U "huggingface_hub[cli]"
  3. Login: hf auth login
  4. Accept the NVIDIA Open Model License Agreement.

Checkpoints are automatically downloaded during inference and post-training. To modify the checkpoint cache location, set the HF_HOME environment variable.