README.md

🤗 Hugging Face  | Cosmos Cookbook

NVIDIA Cosmos Reason – an open, customizable, reasoning vision language model (VLM) for physical AI and robotics - enables robots and vision AI agents to reason like humans, using prior knowledge, physics understanding and common sense to understand and act in the real world. This model understands space, time, and fundamental physics, and can serve as a planning model to reason what steps an embodied agent might take next.

Cosmos Reason excels at navigating the long tail of diverse scenarios of the physical world with spatial-temporal understanding. Cosmos Reason is post-trained with physical common sense and embodied reasoning data with supervised fine-tuning and reinforcement learning. It uses chain-of-thought reasoning capabilities to understand world dynamics without human annotations.

Table of Contents

• News!
• Model Family
• Setup
• Inference
  • Minimum GPU Memory
  • Tested Platforms
  • Transformers
  • Deployment
    • Online Serving
    • Offline Inference
• Post-Training
• Quantization
• Troubleshooting
• Additional Resources
• License and Contact

News!

• [June 1, 2026] Cosmos 3 is live! We’re excited to share that Cosmos 3 has launched — NVIDIA’s next-generation family of open omnimodal world foundation models for Physical AI. As part of this launch, the Cosmos GitHub repositories have moved to the main NVIDIA GitHub organization: https://github.com/nvidia/cosmos. Cosmos 3 unifies language, images, video, audio, and actions in a single architecture, enabling developers to build agents that can understand, reason, simulate, and act in the physical world. Please use the new repository as the source of truth for the latest code, models, documentation, and updates.
• [April 29, 2026] The Cosmos-Reason2-32B model is now available on HuggingFace, along with its performance benchmarks. The 2B and 8B model performance is also included.
• [February 9, 2026] We have Improved documentation and troubleshooting guidance, expanded platform support GB200 and ARM (torchcodec & inference sample fixed), enhanced quantization and training debuggability, and updated CUDA compatibility
• [December 19, 2025] We have released the Cosmos-Reason2 models and code for Physical AI common sense and embodied reasoning. The 2B and 8B models are now available on Hugging Face.

Model Family

• Cosmos-Reason2-2B
• Cosmos-Reason2-8B
• Cosmos-Reason2-32B

Setup

This repository only contains documentation/examples/utilities. You do not need it to run inference. See Inference example for a minimal inference example. The following setup instructions are only needed to run the examples in this repository.

Clone the repository:

git clone https://github.com/nvidia-cosmos/cosmos-reason2.git
cd cosmos-reason2

Install one of the following environments:

sudo apt-get install curl ffmpeg git git-lfs unzip

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

uvx hf auth login

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

export TRITON_PTXAS_PATH="/usr/local/cuda/bin/ptxas"

image_tag=$(docker build -f Dockerfile --build-arg=CUDA_VERSION=12.8.1 -q .)

docker run -it --gpus all --ipc=host --rm -v .:/workspace -v /workspace/.venv -v /workspace/examples/cosmos_rl/.venv -v /root/.cache:/root/.cache -e HF_TOKEN="$HF_TOKEN" $image_tag

Inference

Minimum GPU Memory

Tested Platforms

Cosmos-Reason2 works on Hopper and Blackwell. Additional hardware configurations may work but are not officially validated at the time of this release.

Examples have been tested on the following devices:

Transformers

Cosmos-Reason2 is included in transformers>=4.57.0.

Minimal example (sample output):

python scripts/inference_sample.py

Deployment

For deployment and batch inference, we recommend using vllm>=0.11.0.

Online Serving

Start the server in a separate terminal or a background process.

vllm serve nvidia/Cosmos-Reason2-2B \
  --allowed-local-media-path "$(pwd)" \
  --max-model-len 16384 \
  --media-io-kwargs '{"video": {"num_frames": -1}}' \
  --reasoning-parser qwen3 \
  --port 8000

Optional arguments:

• --max-model-len 16384: Maximum model length to avoid OOM. Recommended range: 8192 - 16384.
• --media-io-kwargs '{"video": {"num_frames": -1}}': Allow overriding FPS per sample.
• --reasoning-parser qwen3: Parse reasoning trace.
• --port 8000: Server port. Change if you encounter Address already in use errors.

Once ready, the server will print Application startup complete..

Caption a video (sample output):

cosmos-reason2-inference online --port 8000 -i prompts/caption.yaml --reasoning --videos assets/sample.mp4 --fps 4

Embodied reasoning with verbose output (sample output):

cosmos-reason2-inference online -v --port 8000 -i prompts/embodied_reasoning.yaml --reasoning --images assets/sample.png

To list available arguments:

cosmos-reason2-inference online --help

Offline Inference

Temporally caption a video and save the input frames to outputs/temporal_localization for debugging (sample output):

cosmos-reason2-inference offline -v --max-model-len 16384 -i prompts/temporal_localization.yaml --videos assets/sample.mp4 --fps 4 -o outputs/temporal_localization

To list available arguments:

cosmos-reason2-inference offline --help

Common arguments:

• --model nvidia/Cosmos-Reason2-2B: Model name or path.

Post-Training

• TRL
• Cosmos-RL

Quantization

• llmcompressor

Troubleshooting

See troubleshooting guide

Additional Resources

• Troubleshooting
• Example prompts
• Cosmos-Reason2 is based on the Qwen3-VL architecture.
  • Qwen3-VL Repository
  • Qwen3-VL vLLM
  • Qwen3 Documentation
• vLLM
  • Online Serving
  • Offline Inference
  • Multimodal Inputs
  • LoRA

License and Contact

This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.

NVIDIA Cosmos source code is released under the Apache 2 License.

NVIDIA Cosmos models are released under the NVIDIA Open Model License. For a custom license, please contact cosmos-license@nvidia.com.