README-comfyui-setup.md

# ComfyUI Fast Setup — Qwen Image Edit (H100)

Reproducible notes for standing up this ComfyUI box quickly. The speed trick is simple: **the base image already had a working CUDA PyTorch stack, so nothing large was reinstalled.**

## Machine
- GPU: NVIDIA H100 80GB HBM3 (CUDA 13.0 driver, 580.x)
- Python 3.12, pre-installed: `torch 2.8.0+cu128`, `torchvision 0.23.0`, `torchaudio 2.8.0` (all CUDA-verified)
- `/workspace` is a network filesystem (MooseFS) — model reads are slow when the OS page cache is cold (e.g. right after a restart). Keep the server running to keep weights resident.

## 1. ComfyUI
```bash
git clone --depth 1 https://github.com/comfyanonymous/ComfyUI.git /workspace/ComfyUI
cd /workspace/ComfyUI
pip install -r requirements.txt        # torch stack already present -> only light deps install
```

## 2. Fast downloads (hf_xet, not hf_transfer)
`huggingface_hub` 1.x ships `hf_xet` (chunked parallel transfer) built in — `hf_transfer` no longer exists.
```bash
export HF_TOKEN=<your token>
```

## 3. Standard Qwen Image Edit models (the reproducible core)
Download straight from the public repos into these paths:

| File | Repo | Dest |
|------|------|------|
| `qwen_image_edit_2511_fp8mixed.safetensors` (20 GB, recommended) | `Comfy-Org/Qwen-Image-Edit_ComfyUI` `split_files/diffusion_models/` | `models/diffusion_models/` |
| `qwen_image_edit_2511_bf16.safetensors` (39 GB, max quality) | same | `models/diffusion_models/` |
| `qwen_2.5_vl_7b_fp8_scaled.safetensors` | `Comfy-Org/HunyuanVideo_1.5_repackaged` `split_files/text_encoders/` | `models/text_encoders/` |
| `qwen_image_vae.safetensors` | `Comfy-Org/Qwen-Image_ComfyUI` `split_files/vae/` | `models/vae/` |
| `Qwen-Image-Edit-2511-Lightning-4steps-V1.0-bf16.safetensors` | `lightx2v/Qwen-Image-Edit-2511-Lightning` | `models/loras/` |

Example (parallelize these for speed):
```bash
hf download Comfy-Org/Qwen-Image-Edit_ComfyUI \
  split_files/diffusion_models/qwen_image_edit_2511_fp8mixed.safetensors \
  --local-dir /tmp/dl && mv /tmp/dl/split_files/diffusion_models/*.safetensors \
  /workspace/ComfyUI/models/diffusion_models/
```

**fp8 vs bf16:** fp8mixed is half the size (20 vs 39 GB), loads ~2x faster, and on an H100 also computes faster with negligible quality loss for edits. Use bf16 only when chasing maximum fidelity.

## 4. Custom nodes
```bash
git clone --depth 1 https://github.com/rgthree/rgthree-comfy.git \
  /workspace/ComfyUI/custom_nodes/rgthree-comfy      # Power Lora Loader
pip install -U comfyui-manager                        # matches bundled manager_requirements.txt (4.2.2)
```
> ComfyUI-Manager installs node deps with `uv pip`, which refuses the system Python (PEP 668).
> If a node's deps fail to install via the Manager UI, install them directly instead:
> `pip install -r custom_nodes/<node>/requirements.txt`

## 5. Run
```bash
cd /workspace/ComfyUI
python3 main.py --listen 0.0.0.0 --port 7865
```

## 6. Workflows built
- **`qwen-loras.json`** — master Qwen edit workflow. Single **"Accelerate?"** boolean toggles
  Lightning-4step + steps(4↔20) + CFG(1.0↔4.0) together. Content LoRAs go in the Power Lora Loader.
- **`qwen-cat-final.json`** — multi-reference edit. A second `LoadImage` feeds `image2` of
  `TextEncodeQwenImageEditPlus`, so an edit can combine two input images (e.g. subject + object).

## Notes / gotchas
- Model load is the slow step over the network FS; it's a one-time cost per server start. Avoid
  restarting mid-session — resident weights make LoRA swaps fast.
- Both `opencv-python` and `-headless` may end up installed by different node packs; same version = fine.
- The `RequestsDependencyWarning` about urllib3/chardet at startup is cosmetic.