Quickstart¶

Install Cosmos-Framework with uv, sign in to Hugging Face, and generate a video from a text prompt with Cosmos3-Nano on one GPU.

Requirements¶

Item	Requirement
GPU	One NVIDIA GPU, Ampere or newer. Cosmos3-Nano's weights alone take about 32 GB of GPU memory.
Driver	The CUDA 13.0 build needs driver 580 or newer. With an older driver, such as 570, use the CUDA 12.8 group (CUDA variants).
OS	Linux x86-64 or aarch64, glibc 2.35 or newer (for example, Ubuntu 22.04 or newer).
Python	3.13, pinned in `.python-version`.
uv	Exactly 0.11.29, pinned in `pyproject.toml`.
Disk	About 150 GiB free: Hugging Face cache ~90 GiB, uv cache ~20 GiB, outputs ~30 GiB.

Install¶

git clone https://github.com/NVIDIA/cosmos-framework.git
cd cosmos-framework
sudo apt-get install -y --no-install-recommends curl ffmpeg git-lfs libgl1 libglib2.0-0 libx11-dev tree wget

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

# CUDA 13.0 (recommended)
uv sync --all-extras --group=cu130-train
# Or, for CUDA 12.8:
# uv sync --all-extras --group=cu128-train
source .venv/bin/activate

Then run the GPU and media checks. To install in a container instead, see the NGC base image or Docker container.

The first run downloads Cosmos3-Nano and the guardrail models from Hugging Face.

Create an access token with Read permission.
Sign in with uvx hf auth login, or export HF_TOKEN (preferred in Docker and non-interactive shells). Use one, not both with different tokens.
Accept the license of any gated model you use.

Test access:

uvx hf@latest download --repo-type model nvidia/Cosmos-Guardrail1 \
  --revision d6d4bfa899a71454a700907664f3e88f503950cf --include "README.md"

To keep the cache on a larger disk, set HF_HOME before the first run.

Generate your first video¶

From the repository root, with the environment active:

python -m cosmos_framework.scripts.inference \
    --parallelism-preset=latency \
    -i "inputs/omni/t2v.json" \
    -o outputs/omni_nano \
    --checkpoint-path Cosmos3-Nano \
    --seed=0

Flag	Meaning
`--parallelism-preset=latency`	The default preset. It only changes the layout on multiple GPUs (parallelism arguments).
`-i`	Sample file. `t2v.json` sets `model_mode` to `text2video`, the sample `name` and the prompt; other fields use built-in defaults.
`-o`	Output directory (required).
`--checkpoint-path`	A model name such as `Cosmos3-Nano`, downloaded from Hugging Face, or a local checkpoint directory.
`--seed`	Random seed for reproducibility.

Check the output¶

Each sample writes to a folder named after its name, t2v here:

outputs/omni_nano/
├── console.log
├── debug.log
├── setup_args.json           # resolved setup
└── t2v/
    ├── sample_args.json      # resolved sample arguments
    ├── sample_outputs.json   # generation status
    └── vision.mp4            # generated video

Running the command again overwrites matching outputs. Pass a new -o directory to keep earlier results.

Troubleshooting¶

Out of GPU memory: see Torch CUDA out of memory, or switch to Cosmos3-Edge, which fits on one GPU and supports every mode except audio.
Download, install or import errors: see Downloading base checkpoints and Setup troubleshooting.

Next steps¶

Install: other install paths, CUDA variants and environment variables.
Run inference: every mode, multi-GPU launches and sample arguments.
Models: which checkpoint fits which task.
Post-training: choose between SFT, distillation and RL.
Deploy: choose a serving path.