NVIDIA Cosmos3 Setup
When to use this skill
- Use when a user wants to install Cosmos3 or set up a development environment
- Use when a user asks about system requirements, CUDA versions, or GPU compatibility
- Use when a user needs to download model checkpoints or configure HuggingFace auth
- Use when a user wants to run Cosmos3 inside a Docker container or NGC container
- For errors during setup, hand off to the cosmos3-env-troubleshoot skill
Path convention
All paths below are relative to the cosmos3 package root (../../../ from this skill file). All uv run / python commands should also be run from there.
Where to find answers
The canonical setup reference is docs/setup.md. The README (README.md § Setup) has the shortest quickstart.
| User question | Go to |
|---|---|
| What are the system requirements? | docs/setup.md § System Requirements |
| How do I install with uv? (sync, pip venv, pip system) | docs/setup.md § Virtual Environment |
| How do I install with Docker? | docs/setup.md § Docker Container |
| Custom torch/CUDA versions or attention backends? | docs/setup.md § Advanced |
| Which CUDA version? (cu130 vs cu128) | docs/setup.md § CUDA Variants, docs/faq.md § Which CUDA version? |
| How do I download checkpoints? | docs/setup.md § Downloading Base Checkpoints |
| NGC container issues? | docs/setup.md § PyTorch Import Issue |
| Any installation error | ../cosmos3-env-troubleshoot/SKILL.md |
Setup steps at a glance
- Clone the repository and
cdinto the project root (the directory containingpyproject.toml) - System deps:
sudo apt-get install -y --no-install-recommends curl ffmpeg git-lfs libx11-dev tree wget - Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh && source $HOME/.local/bin/env - Install package:
uv sync --all-extras --group=cu130-train && source .venv/bin/activate && export LD_LIBRARY_PATH=(usecu128-trainon older drivers; the inference-onlycu130/cu128groups omit the training extras) - Checkpoints: auto-downloaded during inference; requires HuggingFace auth (see docs)
- Verify:
uv run --all-extras --group=cu130-train python -c "import cosmos_framework; print('ok')"
Things not obvious from the docs
- NGC container caveat: you must run
export LD_LIBRARY_PATH=''before any Python imports when inside an NGC PyTorch container. Easy to miss. - CUDA version alignment: the major CUDA version from
nvidia-smimust matchtorch.version.cuda. Mismatches cause cryptic shared-library errors. HF_HOME: controls where checkpoints are cached (default:~/.cache/huggingface). Set this if disk space is tight or you want a shared cache.- Conflicting env vars: stale
HF_TOKENorHUGGING_FACE_HUB_TOKENenv vars can silently override CLI auth. Check withprintenv | grep HF_.
Related skills
| Skill | When to use |
|---|---|
../cosmos3-inference/SKILL.md |
Running inference after setup is complete |
../cosmos3-codebase-nav/SKILL.md |
Finding files, parameters, and configs in code |
../cosmos3-env-troubleshoot/SKILL.md |
Debugging environment and runtime errors |