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