cosmos3-setup git:20260601.1bd5fdcB

Immutable. This exact content is served forever at /api/v1/blob/57c158aab70fd69e.

---
name: cosmos3-setup
description: >
  Guide users through Cosmos3 installation, environment setup, checkpoint downloading,
  and verification. Use when the user asks "how do I install cosmos3", "how do I set up
  the environment", "how do I download checkpoints", "how do I use Docker", or any
  question about getting the package running for the first time.
---

# 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/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

| 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       |