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 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/0.11.29/install.sh | sh && source $HOME/.local/bin/env`. Verify `uv --version` reports `0.11.29`; update an existing installation with `uv self update 0.11.29`. 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_`. - **AutoML is a separate source install**: `uv sync --all-extras` does not install the core engine. For AutoML setup, follow `docs/automl.md#installation-from-source` and the `cosmos-automl` skill: ask whether to use `NVIDIA-TAO/tao-automl`'s `main` branch or a user-selected development branch before a new installation. Keep the recorded source revision for existing experiments; do not upgrade on resume. ## 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 |