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.

Setup steps at a glance

1. Clone the repository and cd into the project root (the directory containing pyproject.toml)
2. System deps: sudo apt-get install -y --no-install-recommends curl ffmpeg git-lfs libx11-dev tree wget
3. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh && source $HOME/.local/bin/env
4. 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)
5. Checkpoints: auto-downloaded during inference; requires HuggingFace auth (see docs)
6. 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