Cosmos3 Setup

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 cd into the project root (the directory containing pyproject.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= (use cu128-train on older drivers; the inference-only cu130 / cu128 groups 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-smi must match torch.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_TOKEN or HUGGING_FACE_HUB_TOKEN env vars can silently override CLI auth. Check with printenv | 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 |