# ComfyUI User Guide

**ComfyUI** is a powerful, modular, node-based graphical user interface and inference backend for running generative AI models locally. Users construct processing pipelines — called **workflows** — by visually connecting nodes in a directed graph. The server runs on Python with an aiohttp backend (default port `8188`) and a browser-based frontend that requires no installation beyond the main package.

This guide covers everything from first installation through advanced workflow construction, every CLI flag, all model directory conventions, troubleshooting, and a comprehensive FAQ. See the Admin Guide for architecture internals, API endpoint reference, and deployment configuration.

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Installation](#2-installation)
3. [Configuration](#3-configuration)
4. [Core Usage](#4-core-usage)
5. [Common Tasks](#5-common-tasks)
6. [Troubleshooting](#6-troubleshooting)
7. [FAQ](#7-faq)

---

## 1. Quick Start

Get ComfyUI generating images in under 10 minutes on a machine with an NVIDIA GPU.

### 1.1 Prerequisites

| Requirement | Minimum | Recommended |
|---|---|---|
| GPU | NVIDIA 6 GB VRAM | NVIDIA 12+ GB VRAM |
| RAM | 8 GB | 16+ GB |
| Disk | 10 GB free | 50+ GB for models |
| Python | 3.10 | 3.12 |
| OS | Windows 10 / Ubuntu 20.04 / macOS 12 | Windows 11 / Ubuntu 22.04 |
| CUDA | 11.8 | 12.4 |

> [!TIP]
> If you don't have an NVIDIA GPU, ComfyUI also supports AMD (ROCm), Apple Silicon (MPS), Intel Arc (oneAPI/DirectML), and CPU-only mode. See [Section 2.3 — Platform-Specific Installation](#23-platform-specific-installation) for details.

### 1.2 Five-Minute Launch

```bash
# 1. Clone the repository
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI

# 2. Install Python dependencies (PyTorch + CUDA 12.4 shown)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

# 3. Drop a checkpoint model into models/checkpoints/
#    (e.g., v1-5-pruned-emaonly.safetensors from Hugging Face)

# 4. Start the server
python main.py

# 5. Open your browser
#    → http://127.0.0.1:8188
```

Expected terminal output:

```text
Total VRAM 24576 MB, total RAM 65536 MB
Prompt server running on http://127.0.0.1:8188
```

> [!TIP]
> Add `--auto-launch` to have ComfyUI open your browser automatically on startup.

### 1.3 Your First Image (30-Second Workflow)

ComfyUI ships with a **default workflow** pre-loaded in the interface. It connects six core nodes:

```
[Load Checkpoint] → [CLIP Text Encode (Positive)] ──┐
                  → [CLIP Text Encode (Negative)]  ──┤→ [KSampler] → [VAE Decode] → [Save Image]
                  → [Empty Latent Image] ────────────┘
```

1. In the **positive prompt** node, type a description: `a photorealistic cat sitting on a windowsill, golden hour lighting`
2. In the **negative prompt** node, type: `blurry, low quality, deformed`
3. Click **Queue Prompt** (or press `Ctrl+Enter`)
4. Watch the progress bar — your image appears in the **Save Image** node and saves to `output/`

---

## 2. Installation

### 2.1 Standard Installation (NVIDIA GPU)

#### Step 1 — Clone

```bash
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
```

#### Step 2 — Install PyTorch

Choose the command for your CUDA version:

```bash
# CUDA 12.4 (recommended for RTX 30xx, 40xx, 50xx)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

# CUDA 11.8 (older GPUs)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
```

#### Step 3 — Install ComfyUI Dependencies

```bash
pip install -r requirements.txt
```

The `requirements.txt` installs (among others):

| Package | Purpose |
|---|---|
| `comfyui-frontend-package==1.42.11` | Web UI frontend (auto-downloaded) |
| `comfyui-workflow-templates==0.9.54` | Built-in workflow blueprints |
| `comfyui-embedded-docs==0.4.3` | In-app documentation |
| `torch`, `torchvision`, `torchaudio` | Deep learning framework |
| `transformers>=4.50.3` | Hugging Face model loading |
| `safetensors>=0.4.2` | Fast model file format |
| `aiohttp>=3.11.8` | Async HTTP server |
| `Pillow` | Image I/O |
| `scipy`, `tqdm`, `psutil` | Scientific computing, progress, system info |
| `alembic`, `SQLAlchemy` | Database migrations |
| `av>=14.2.0` | Video codec support |
| `blake3` | Fast file hashing |
| `spandrel` | Upscale model loader |
| `kornia>=0.7.1` | Computer vision transforms |
| `pydantic~=2.0`, `pydantic-settings~=2.0` | Settings validation |

> [!IMPORTANT]
> Install PyTorch **before** running `pip install -r requirements.txt`. The requirements file does not specify a PyTorch index URL, so installing in the wrong order may pull a CPU-only PyTorch build from PyPI.

#### Step 4 — Add a Model

ComfyUI does not include models. Download a checkpoint and place it in `models/checkpoints/`:

```bash
# Example: download SDXL base from Hugging Face CLI
pip install huggingface_hub
huggingface-cli download stabilityai/stable-diffusion-xl-base-1.0 sd_xl_base_1.0.safetensors --local-dir models/checkpoints/
```

#### Step 5 — Launch

```bash
python main.py
```

> [!WARNING]
> Do NOT run `python main.py` as root/Administrator unless you explicitly trust all custom nodes loaded. Custom nodes execute arbitrary Python at startup.

---

### 2.2 Virtual Environment (Recommended)

Using a virtual environment prevents dependency conflicts:

```bash
# Create
python -m venv venv

# Activate (Linux/macOS)
source venv/bin/activate

# Activate (Windows CMD)
venv\Scripts\activate.bat

# Activate (Windows PowerShell)
venv\Scripts\Activate.ps1

# Then install as normal
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
```

---

### 2.3 Platform-Specific Installation

#### AMD GPU (Linux — ROCm)

```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.2
pip install -r requirements.txt
python main.py
```

#### AMD GPU (Windows — DirectML)

```bash
pip install torch-directml
pip install -r requirements.txt
python main.py --directml
```

#### Apple Silicon (M1/M2/M3/M4 — MPS)

```bash
# macOS ships its own Python — use a venv
python3 -m venv venv && source venv/bin/activate
pip install torch torchvision torchaudio
pip install -r requirements.txt
python main.py
```

ComfyUI auto-detects MPS. No extra flag needed. fp16 is supported; fp8 is not (see FAQ).

#### Intel Arc (oneAPI)

```bash
pip install torch torchvision torchaudio --index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/us/
pip install -r requirements.txt
python main.py --oneapi-device-selector ext_oneapi_level_zero:gpu:0
```

#### CPU-Only

```bash
pip install torch torchvision torchaudio
pip install -r requirements.txt
python main.py --cpu
```

> [!WARNING]
> CPU-only mode is extremely slow — expect minutes per image step on modern hardware. Only use it for testing or on machines with no usable GPU.

---

### 2.4 Windows Standalone Build

ComfyUI provides a Windows standalone `.7z` package with a pre-bundled Python and PyTorch environment. Download from the [official releases page](https://github.com/comfyanonymous/ComfyUI/releases) and run `run_nvidia_gpu.bat`.

The standalone build automatically sets `--windows-standalone-build`, which enables:
- Auto-launch (opens browser on start)
- Convenience features for single-user local use

---

### 2.5 Updating ComfyUI

```bash
git pull
pip install -r requirements.txt
```

> [!NOTE]
> After major updates, custom nodes may need updating too. Use ComfyUI-Manager (if installed) to update all custom nodes at once.

---

## 3. Configuration

### 3.1 Complete CLI Reference — All 94 Flags

Start ComfyUI with `python main.py [OPTIONS]`. All flags are optional.

#### Network Flags

| Flag | Default | Description |
|---|---|---|
| `--listen [IP]` | `127.0.0.1` | IP address to listen on. Passing `--listen` alone (no IP) binds to `0.0.0.0,::` (all interfaces, IPv4 + IPv6). Set to `0.0.0.0` to allow LAN access. |
| `--port PORT` | `8188` | TCP port for the HTTP server. |
| `--tls-keyfile PATH` | — | Path to TLS private key file (enables HTTPS when combined with `--tls-certfile`). |
| `--tls-certfile PATH` | — | Path to TLS certificate file (enables HTTPS). |
| `--enable-cors-header [ORIGIN]` | disabled | Enable CORS headers. Pass a specific origin or omit the argument to allow all origins (`*`). |
| `--max-upload-size FLOAT` | `100` | Maximum upload size in megabytes. Applies to image/video uploads via the API. |
| `--enable-compress-response-body` | disabled | Gzip-compress HTTP responses. Useful when serving over slow connections. |

**Examples:**

```bash
# Expose on LAN (all interfaces)
python main.py --listen

# Custom port
python main.py --port 8080

# HTTPS with self-signed cert
python main.py --tls-keyfile certs/key.pem --tls-certfile certs/cert.pem

# Allow any CORS origin
python main.py --enable-cors-header

# Allow a specific origin
python main.py --enable-cors-header https://myapp.example.com

# Increase upload limit to 2 GB
python main.py --max-upload-size 2000
```

---

#### Directory Flags

| Flag | Default | Description |
|---|---|---|
| `--base-directory PATH` | Script directory | Root directory that sets the default location for models, custom_nodes, input, output, temp, and user directories. All other directory flags override this. |
| `--extra-model-paths-config PATH [PATH...]` | — | One or more paths to `extra_model_paths.yaml` files. Lets you map model folders from other installations (A1111, etc.). |
| `--output-directory PATH` | `<base>/output` | Where generated images/videos are saved. Overrides `--base-directory` for output only. |
| `--temp-directory PATH` | `<base>/temp` | Temporary file storage. Overrides `--base-directory` for temp only. |
| `--input-directory PATH` | `<base>/input` | Where the "Load Image" node looks for input files. |
| `--user-directory PATH` | `<base>/user` | Per-user data (saved workflows, settings). |

**Example — point ComfyUI at a shared model library:**

```bash
python main.py --base-directory /mnt/ai-data
# Now uses /mnt/ai-data/models/, /mnt/ai-data/output/, etc.

# Override just output:
python main.py --base-directory /mnt/ai-data --output-directory ~/Pictures/comfyui-output
```

**Using `extra_model_paths.yaml`:**

```yaml
# extra_model_paths.yaml
a1111:
    base_path: /home/user/stable-diffusion-webui
    checkpoints: models/Stable-diffusion
    vae: models/VAE
    loras: models/Lora
    embeddings: embeddings
    hypernetworks: models/hypernetworks
    controlnet: models/ControlNet
    upscale_models: models/ESRGAN
```

```bash
python main.py --extra-model-paths-config /path/to/extra_model_paths.yaml
```

---

#### Launch Flags

| Flag | Default | Description |
|---|---|---|
| `--auto-launch` | disabled | Open the default browser automatically when the server starts. |
| `--disable-auto-launch` | — | Explicitly disable auto-launch (useful when `--windows-standalone-build` would otherwise enable it). |
| `--windows-standalone-build` | disabled | Enable auto-launch and other convenience features for standalone Windows builds. |

---

#### GPU / Device Flags

| Flag | Default | Description |
|---|---|---|
| `--cuda-device DEVICE_ID` | — | Restrict ComfyUI to a specific CUDA device (e.g., `0`, `1`). Hides other GPUs from torch. |
| `--default-device DEFAULT_DEVICE_ID` | — | Set the default inference device while keeping other devices visible. |
| `--cuda-malloc` | auto | Enable CUDA malloc allocator optimizations. |
| `--disable-cuda-malloc` | — | Disable CUDA malloc optimizations. |
| `--directml [DEVICE]` | — | Use the `torch-directml` backend (Windows AMD/Intel). Omit DEVICE for default. |
| `--oneapi-device-selector SELECTOR` | — | Restrict to a specific oneAPI device (e.g., `ext_oneapi_level_zero:gpu:0`). |
| `--disable-ipex-optimize` | — | Disable Intel IPEX optimizations when using Intel Arc. |
| `--supports-fp8-compute` | auto | Force-enable fp8 compute even on hardware that doesn't advertise support. |

---

#### Precision Flags

> [!NOTE]
> These flags override ComfyUI's automatic precision selection. In most cases, the defaults are optimal. Only change these if you experience quality or speed issues.

**Global Precision (mutually exclusive):**

| Flag | Description |
|---|---|
| `--force-fp32` | Use 32-bit floats everywhere. Highest quality, highest VRAM usage. |
| `--force-fp16` | Use 16-bit floats everywhere. Faster, lower VRAM, minor quality tradeoff. |

**UNet / Diffusion Model Precision (pick one):**

| Flag | Description |
|---|---|
| `--fp32-unet` | Run UNet in fp32. |
| `--fp64-unet` | Run UNet in fp64. Very slow, rarely needed. |
| `--bf16-unet` | Run UNet in bfloat16. Better dynamic range than fp16. |
| `--fp16-unet` | Run UNet in fp16. |
| `--fp8_e4m3fn-unet` | Run UNet in fp8 (e4m3fn format). Dramatic VRAM savings, requires fp8-capable hardware. |
| `--fp8_e5m2-unet` | Run UNet in fp8 (e5m2 format). |
| `--fp8_e8m0fnu-unet` | Run UNet in fp8 (e8m0fnu format). |

**VAE Precision (pick one):**

| Flag | Description |
|---|---|
| `--fp16-vae` | Run VAE in fp16. May cause color artifacts with some models. |
| `--fp32-vae` | Run VAE in fp32. Default for most models; avoids decode artifacts. |
| `--bf16-vae` | Run VAE in bfloat16. |
| `--cpu-vae` | Run VAE on CPU. Useful when GPU VRAM is exhausted by large batches. |

**Text Encoder Precision (pick one):**

| Flag | Description |
|---|---|
| `--fp8_e4m3fn-text-enc` | Text encoder in fp8 (e4m3fn). |
| `--fp8_e5m2-text-enc` | Text encoder in fp8 (e5m2). |
| `--fp16-text-enc` | Text encoder in fp16. |
| `--fp32-text-enc` | Text encoder in fp32. |
| `--bf16-text-enc` | Text encoder in bfloat16. |

**Other Precision:**

| Flag | Description |
|---|---|
| `--fp16-intermediates` | (Experimental) Store intermediate tensors in fp16. Reduces VRAM mid-pass. |
| `--force-channels-last` | Force NHWC memory layout. Can improve performance on some hardware. |

---

#### VRAM Management Flags (pick one from the main group)

> [!IMPORTANT]
> ComfyUI auto-detects your VRAM and picks an appropriate mode. Only override if you're getting OOM errors or the auto-detected mode is wrong.

| Flag | Description |
|---|---|
| `--gpu-only` | Keep all models on GPU permanently. Fastest for high-VRAM cards (24+ GB). |
| `--highvram` | Keep models in GPU VRAM after generation (don't offload). Good for 12–16 GB. |
| `--normalvram` | Force normal mode even if auto-detection would pick lowvram. |
| `--lowvram` | Split the UNet into parts and process them sequentially. For 4–6 GB GPUs. |
| `--novram` | More aggressive than lowvram — run UNet entirely on CPU for the weights. For 2–4 GB GPUs. |
| `--cpu` | Use CPU for all computation. No GPU required; very slow. |

**Additional VRAM Control:**

| Flag | Default | Description |
|---|---|---|
| `--reserve-vram FLOAT` | auto | GB of VRAM to reserve for the OS/other apps. E.g., `--reserve-vram 1.0` reserves 1 GB. |
| `--async-offload [NUM_STREAMS]` | `2` (NVIDIA auto-enabled) | Overlap CPU↔GPU transfers with computation using `NUM_STREAMS` CUDA streams. |
| `--disable-async-offload` | — | Disable async offloading even on NVIDIA hardware. |
| `--disable-dynamic-vram` | — | Disable dynamic VRAM management (may reduce stuttering on some workloads). |
| `--enable-dynamic-vram` | — | Force-enable dynamic VRAM management. |
| `--force-non-blocking` | — | Force non-blocking tensor operations. |
| `--disable-smart-memory` | — | Disable ComfyUI's smart memory allocation. Falls back to simpler management. |

**VRAM strategy guide:**

| GPU VRAM | Recommended flags |
|---|---|
| 4 GB | `--lowvram --fp16-unet` |
| 6 GB | (auto-detect, or `--lowvram`) |
| 8 GB | `--normalvram --fp16-unet` |
| 12 GB | `--highvram` |
| 16 GB | `--highvram` |
| 24 GB+ | `--gpu-only` |

---

#### Attention Mechanism Flags (pick one)

These control which attention implementation handles cross-attention in the UNet:

| Flag | Description |
|---|---|
| `--use-split-cross-attention` | Split cross-attention. Fallback for when xformers isn't available. |
| `--use-quad-cross-attention` | Quad cross-attention (slice approach). |
| `--use-pytorch-cross-attention` | PyTorch's built-in scaled dot-product attention (sdp). |
| `--use-sage-attention` | SAGE attention — a hardware-efficient alternative. |
| `--use-flash-attention` | Flash Attention 2/3. Requires the `flash-attn` package. Very fast on Ampere+. |
| `--disable-xformers` | Disable xformers even if installed. |
| `--force-upcast-attention` | Force attention computation in fp32 for stability. |
| `--dont-upcast-attention` | Prevent attention from being upcast (keep in fp16). |

> [!TIP]
> On modern NVIDIA cards (Ampere+, i.e., RTX 3000+), PyTorch's built-in `sdp` attention is typically fastest without extra packages. For maximum speed, install `flash-attn` and use `--use-flash-attention`.

---

#### Cache Flags (pick one)

These control how ComfyUI caches intermediate results to avoid recomputation when only part of a workflow changes:

| Flag | Default | Description |
|---|---|---|
| `--cache-classic` | disabled | Aggressive caching — cache everything possible. Uses more RAM/VRAM. |
| `--cache-lru N` | disabled | LRU cache with `N` maximum cached items. Balances speed and memory. |
| `--cache-none` | disabled | No caching. Every node recomputes each run. Saves memory; slower for iterative edits. |
| `--cache-ram [THRESHOLD_GB]` | disabled | Cache to RAM based on memory pressure. Default threshold: 25% of total RAM, minimum 4 GB, maximum 32 GB. |

> [!TIP]
> For iterative prompt editing on a single workflow, `--cache-classic` dramatically speeds up runs because unchanged nodes (like the checkpoint loader) are not re-executed. For batch processing diverse workflows, `--cache-none` prevents stale results.

---

#### Preview Flags

| Flag | Default | Description |
|---|---|---|
| `--preview-method [METHOD]` | `none` | How to show in-progress latent previews. Options: `none`, `auto`, `latent2rgb`, `taesd`. |
| `--preview-size INT` | `512` | Maximum pixel dimension for preview images. |

**Preview method comparison:**

| Method | Speed | Quality | Requirements |
|---|---|---|---|
| `none` | — | No previews | Nothing |
| `latent2rgb` | Fast | Low (abstract colors) | Nothing |
| `taesd` | Medium | Good (recognizable) | TAESD models in `models/vae_approx/` |
| `auto` | Varies | Best available | Auto-selects taesd if models present |

---

#### Performance Flags

| Flag | Default | Description |
|---|---|---|
| `--fast [FEATURES...]` | disabled | Enable performance optimizations. Pass no arguments for all features, or specify: `fp16_accumulation`, `fp8_matrix_mult`, `cublas_ops`, `autotune`. |
| `--deterministic` | disabled | Force deterministic algorithms. Results are reproducible but generation is slower. |
| `--disable-pinned-memory` | — | Disable pinned (page-locked) CPU memory. Use if you see excessive RAM usage. |
| `--mmap-torch-files` | disabled | Memory-map model files instead of loading them into RAM. Faster cold-start; may be slower during inference. |
| `--disable-mmap` | — | Disable memory mapping. |
| `--default-hashing-function [ALGO]` | `sha256` | Algorithm for model file integrity checks. Options: `md5`, `sha1`, `sha256`, `sha512`. |

---

#### Manager Flags

| Flag | Description |
|---|---|
| `--enable-manager` | Enable the ComfyUI Manager subsystem (for installing custom nodes). |
| `--disable-manager-ui` | Keep the manager backend but hide the UI. |
| `--enable-manager-legacy-ui` | Use the older manager UI instead of the current one. |

---

#### Custom Node Flags

| Flag | Description |
|---|---|
| `--disable-all-custom-nodes` | Do not load any custom nodes from `custom_nodes/`. Useful for debugging. |
| `--whitelist-custom-nodes FOLDERS...` | Only load the specified custom node folders (space-separated). |
| `--disable-api-nodes` | Disable the built-in API nodes (external service integrations). |

---

#### Other / Miscellaneous Flags

| Flag | Default | Description |
|---|---|---|
| `--multi-user` | disabled | Enable per-user storage (separate workflow/settings per session). |
| `--verbose [LEVEL]` | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. |
| `--log-stdout` | disabled | Write log output to stdout instead of stderr. |
| `--disable-metadata` | disabled | Do not embed prompt metadata into generated image files. |
| `--front-end-version OWNER/REPO@VERSION` | package default | Pin the frontend to a specific GitHub release (e.g., `Comfy-Org/ComfyUI_frontend@1.40.0`). |
| `--front-end-root PATH` | auto | Use a local directory as the frontend instead of the auto-downloaded package. |
| `--comfy-api-base URL` | `https://api.comfy.org` | Base URL for the Comfy cloud API (used by API nodes). |
| `--database-url URL` | `sqlite:///user/comfyui.db` | Database connection URL for user data. SQLite default; can point to PostgreSQL. |
| `--enable-assets` | disabled | Enable the asset management system. |
| `--dont-print-server` | disabled | Suppress the startup URL print. |
| `--quick-test-for-ci` | disabled | Run startup checks and exit immediately. Used in CI/CD pipelines. |

---

### 3.2 extra_model_paths.yaml — Sharing Models Across Tools

If you use multiple AI tools (Stable Diffusion WebUI, InvokeAI, etc.), you can point ComfyUI at their model directories instead of duplicating large files.

Copy `extra_model_paths.yaml.example` to `extra_model_paths.yaml`:

```bash
cp extra_model_paths.yaml.example extra_model_paths.yaml
```

Edit to match your setup:

```yaml
# extra_model_paths.yaml

# Point at Automatic1111 / SD WebUI
a1111:
    base_path: C:/stable-diffusion-webui    # or /home/user/stable-diffusion-webui
    checkpoints: models/Stable-diffusion
    vae: models/VAE
    loras: models/Lora
    controlnet: models/ControlNet
    embeddings: embeddings
    hypernetworks: models/hypernetworks
    upscale_models: models/ESRGAN

# Point at a shared network drive
shared_nas:
    base_path: /mnt/nas/ai-models
    checkpoints: checkpoints
    loras: loras
    vae: vae
```

The file is automatically detected if placed next to `main.py`. Pass it explicitly with `--extra-model-paths-config`:

```bash
python main.py --extra-model-paths-config /path/to/extra_model_paths.yaml /path/to/another.yaml
```

---

### 3.3 Model Directories Reference

All model directories live under `models/` (or the path set by `--base-directory`):

| Directory | Model Types | Example Files |
|---|---|---|
| `models/checkpoints/` | Full SD checkpoints (UNet + CLIP + VAE bundled) | `v1-5-pruned-emaonly.safetensors`, `sd_xl_base_1.0.safetensors` |
| `models/clip/` | Standalone CLIP text encoders | `clip_l.safetensors`, `t5xxl_fp16.safetensors` |
| `models/clip_vision/` | CLIP vision encoders (for IP-Adapter, style transfer) | `clip_vision_g.safetensors` |
| `models/controlnet/` | ControlNet and T2I Adapter models | `control_v11p_sd15_canny.safetensors` |
| `models/diffusion_models/` | Standalone UNet/diffusion models (Flux, etc.) | `flux1-dev.safetensors` |
| `models/diffusers/` | Hugging Face Diffusers format model directories | `stable-diffusion-xl-base-1.0/` |
| `models/embeddings/` | Textual inversion embeddings | `EasyNegative.pt`, `bad_anatomy.pt` |
| `models/gligen/` | GLIGEN layout-grounded models | `gligen_sd14_textbox_pruned.safetensors` |
| `models/hypernetworks/` | Hypernetwork files | `anime_v2.pt` |
| `models/loras/` | LoRA (Low-Rank Adaptation) models | `lcm_lora_sdxl.safetensors` |
| `models/model_patches/` | Model patch files | — |
| `models/photomaker/` | PhotoMaker identity models | `photomaker-v1.bin` |
| `models/style_models/` | T2I style conditioning models | `t2i-adapter-sdxl-sketch.safetensors` |
| `models/text_encoders/` | Standalone text encoder files | `umt5-xxl-enc-bf16.safetensors` |
| `models/unet/` | Standalone UNet files | `dreamshaper_8_unet.safetensors` |
| `models/upscale_models/` | ESRGAN and other super-resolution models | `4x-UltraSharp.pth`, `RealESRGAN_x4plus.pth` |
| `models/vae/` | Variational Autoencoders | `vae-ft-mse-840000-ema-pruned.safetensors` |
| `models/vae_approx/` | TAESD fast VAE approximators (for previews) | `taesd_decoder.pth`, `taesdxl_decoder.pth` |
| `models/audio_encoders/` | Audio encoding models | — |
| `models/latent_upscale_models/` | Latent-space upscale models | — |
| `models/configs/` | Model config YAML files | `v1-inference.yaml`, `v2-inference-v.yaml`, `anything_v3.yaml` |

> [!NOTE]
> ComfyUI searches subdirectories recursively within each model folder. You can organize models into subfolders (e.g., `models/loras/sdxl/`, `models/loras/sd15/`) and they will all be found.

---

### 3.4 Settings File (user/default/comfy.settings.json)

Per-user settings are stored in `user/default/comfy.settings.json`. These are managed through the **Settings** panel in the UI (gear icon → Settings). Key settings include:

- Canvas zoom speed and behavior
- Auto-save interval
- Default sampler and scheduler
- Preview method (overrides CLI default per-user)
- Theme (dark/light)
- Node snapping grid size

---

## 4. Core Usage

### 4.1 The Interface

The ComfyUI frontend is a full-screen canvas application. Key interface areas:

| Area | Location | Purpose |
|---|---|---|
| **Canvas** | Center | Drag, zoom, and connect nodes |
| **Queue panel** | Right sidebar | View pending/running/completed jobs |
| **Node library** | Left sidebar (or double-click canvas) | Browse and add nodes |
| **Top bar** | Top | Load/save workflow, queue controls, settings |
| **Bottom status** | Bottom | Execution progress, VRAM/RAM indicators |

**Navigation shortcuts:**

| Action | Shortcut |
|---|---|
| Pan canvas | Middle-click drag / Space+drag |
| Zoom | Scroll wheel |
| Fit all nodes | `F` |
| Select all | `Ctrl+A` |
| Copy nodes | `Ctrl+C` |
| Paste nodes | `Ctrl+V` |
| Undo | `Ctrl+Z` |
| Redo | `Ctrl+Y` |
| Queue prompt | `Ctrl+Enter` |
| Save workflow | `Ctrl+S` |
| Load workflow | `Ctrl+O` |
| Add node | Double-click canvas |
| Delete node | `Delete` / `Backspace` |
| Bypass node | `Ctrl+B` |
| Pin/unpin node | `Ctrl+P` |
| Group nodes | `Ctrl+G` |

---

### 4.2 Nodes — The Building Blocks

Every operation in ComfyUI is a **node**. Nodes have:

- **Input slots** (left side, colored dots) — receive data from other nodes
- **Output slots** (right side, colored dots) — send data to other nodes
- **Widgets** — input fields, dropdowns, sliders embedded in the node

**Connection color coding:**

| Color | Data Type |
|---|---|
| Yellow/Gold | `MODEL` (checkpoint/UNet) |
| Pink/Magenta | `CONDITIONING` (text embeddings) |
| Light Blue | `LATENT` (compressed image tensor) |
| Orange | `IMAGE` (pixel-space image tensor) |
| Purple | `VAE` |
| Teal/Cyan | `CLIP` |
| Red | `CONTROL_NET` |
| Green | `MASK` |
| White | `STRING`, `INT`, `FLOAT`, `BOOL` |

**Rules for connecting nodes:**
- Output type must match input type (same color)
- One output can connect to multiple inputs
- One input accepts only one connection (connecting a second disconnects the first)

---

### 4.3 Core Node Reference

#### Loading Models

**Load Checkpoint**
- Inputs: none
- Outputs: `MODEL`, `CLIP`, `VAE`
- Widget: `ckpt_name` — dropdown of files in `models/checkpoints/`
- Use: Load a full `.safetensors` or `.ckpt` checkpoint

**Load Diffusion Model** (aka Load UNet)
- Inputs: none
- Outputs: `MODEL`
- Widget: `unet_name`, `weight_dtype`
- Use: Load a standalone diffusion model (Flux, SD3, etc.)

**Load VAE**
- Outputs: `VAE`
- Widget: `vae_name`
- Use: Load a standalone VAE from `models/vae/`

**DualCLIPLoader**
- Outputs: `CLIP`
- Widgets: `clip_name1`, `clip_name2`, `type`
- Use: Load two CLIP models (required for Flux, SD3, etc.)

**Load LoRA**
- Inputs: `MODEL`, `CLIP`
- Outputs: `MODEL`, `CLIP`
- Widgets: `lora_name`, `strength_model`, `strength_clip`
- Use: Apply a LoRA adapter. Chain multiple Load LoRA nodes for multiple LoRAs.

**Load CLIP Vision**
- Outputs: `CLIP_VISION`
- Widget: `clip_name` — dropdown from `models/clip_vision/`
- Use: Load a CLIP vision encoder for IP-Adapter, SVD, style-based workflows

---

#### Text Encoding

**CLIP Text Encode (Prompt)**
- Inputs: `CLIP`
- Outputs: `CONDITIONING`
- Widget: `text` (multi-line prompt)
- Use: Encode positive or negative prompts into conditioning vectors

**Prompt syntax:**
```text
# Basic positive prompt
a cat, oil painting, masterpiece, 8k

# Attention weighting — increase weight with ()
(beautiful cat:1.3), oil painting

# Decrease weight
plain background, (bad anatomy:0.5)

# BREAK keyword — start new chunk
beautiful landscape BREAK forest, trees, detailed
```

---

#### Sampling (the Core Loop)

**KSampler**
- Inputs: `MODEL`, `positive`, `negative`, `latent_image`
- Outputs: `LATENT`
- Widgets:

| Widget | Description |
|---|---|
| `seed` | Random seed. `-1` = random each run. |
| `control_after_generate` | `fixed`, `increment`, `decrement`, `randomize` |
| `steps` | Denoising steps (10–30 typical) |
| `cfg` | Classifier-free guidance scale (1–20, typical 5–10) |
| `sampler_name` | Sampling algorithm (see table below) |
| `scheduler` | Noise schedule (see table below) |
| `denoise` | Fraction of denoising (1.0 = full generation, <1.0 = img2img) |

**Available samplers:**

| Category | Samplers |
|---|---|
| Euler family | `euler`, `euler_cfg_pp`, `euler_ancestral`, `euler_ancestral_cfg_pp` |
| Heun | `heun`, `heun_pp2` |
| DPM-2 | `dpm_2`, `dpm_2_ancestral` |
| LMS | `lms` |
| DPM fast/adaptive | `dpm_fast`, `dpm_adaptive` |
| DPM++ family | `dpmpp_2s_ancestral`, `dpmpp_sde`, `dpmpp_sde_gpu`, `dpmpp_2m`, `dpmpp_2m_cfg_pp`, `dpmpp_2m_sde`, `dpmpp_2m_sde_gpu`, `dpmpp_3m_sde`, `dpmpp_3m_sde_gpu` |
| DDPM | `ddpm` |
| LCM / Lightning | `lcm`, `ipndm`, `ipndm_v` |
| DEIS | `deis` |
| Residual | `res_multistep`, `res_multistep_cfg_pp` |
| Gradient | `gradient`, `gradient_cfg_pp` |
| Other | `er_sde`, `seeds_2`, `seeds_3`, `ddim`, `uni_pc`, `uni_pc_bh2` |

**Available schedulers:**

`normal`, `karras`, `exponential`, `sgm_uniform`, `simple`, `ddim_uniform`, `beta`, `linear_quadratic`, `kl_optimal`, `align_your_steps`, `gits`

> [!TIP]
> For Stable Diffusion 1.5/SDXL: `euler_ancestral` + `karras` at 20 steps is a reliable default. For Flux: `euler` + `simple` at 20–28 steps.

**KSamplerAdvanced** — exposes `add_noise`, `noise`, `start_at_step`, `end_at_step`, `return_with_leftover_noise` for fine-grained control over multi-pass workflows.

---

#### Latent Space

**Empty Latent Image**
- Outputs: `LATENT`
- Widgets: `width`, `height`, `batch_size`
- Use: Create a blank latent tensor for text-to-image generation

**Empty SD3 Latent Image**
- Outputs: `LATENT`
- Use: Specifically sized for SD3/Flux architecture latent tensors

**VAE Encode**
- Inputs: `pixels` (IMAGE), `VAE`
- Outputs: `LATENT`
- Use: Convert a pixel-space image to latent space (for img2img)

**VAE Decode**
- Inputs: `LATENT`, `VAE`
- Outputs: `IMAGE`
- Use: Convert latent tensor back to pixel-space image

**Latent Upscale**
- Inputs: `LATENT`
- Outputs: `LATENT`
- Widgets: `upscale_method`, `width`, `height`, `crop`
- Use: Resize latent tensors (bilinear, bicubic, etc.)

---

#### Image I/O

**Load Image**
- Outputs: `IMAGE`, `MASK`
- Widget: `image` — file picker from `input/` directory
- Supports: PNG, JPEG, WebP, BMP, TIFF

**Save Image**
- Inputs: `images` (IMAGE)
- Widgets: `filename_prefix`, `format`, `quality`
- Saves to: `output/` directory (or `--output-directory` path)
- Embeds: prompt metadata in PNG chunks (disable with `--disable-metadata`)

**Preview Image**
- Like Save Image but saves to `temp/` — not kept long-term. Use for intermediate results.

**Load Image (from URL)** — via custom nodes; not built-in. Use **Load Image** and upload via the UI.

---

#### Mask Nodes

**MaskToImage / ImageToMask**
- Convert between mask and image tensor formats

**Grow Mask / Blur Mask / Invert Mask**
- Morphological operations on masks for inpainting preparation

**Mask Editor** (right-click Load Image → Open in MaskEditor)
- Draw masks directly in the browser on loaded images

---

### 4.4 Built-in Extra Nodes (comfy_extras)

ComfyUI ships 99+ extra node files covering specialized capabilities:

**Sampling & Conditioning:**

| Node Category | Key Nodes |
|---|---|
| Advanced samplers | Custom sampler components, noise injection |
| Conditioning | Conditioning combine, average, concat, set area |
| CFG variants | CFG Guider, PAG (Perturbed Attention), APG, NAG, SLG, TCFG, PerpNeg, SAG, FreeU, FrEScA |
| Align Your Steps | Scheduler nodes for AYS method |
| GITS / OptimalSteps | Adaptive step schedulers |

**Image Processing:**

| Node Category | Key Nodes |
|---|---|
| Post-processing | Sharpen, blur, normalize |
| Compositing | Image composite, alpha channel |
| Canny edges | Canny edge detection preprocessor |
| Morphology | Erode, dilate, open, close |
| Color adjustment | Hue/saturation/brightness |
| Mask operations | Mask grow, shrink, feather |

**Video:**

| Node File | Purpose |
|---|---|
| `nodes_video.py` | Video loading, combining, frame extraction |
| `nodes_video_model.py` | SVD and video model conditioning |
| `nodes_wan.py` | Wan 2.1 video generation |
| `nodes_wanmove.py` | Wan motion-based video |
| `nodes_lt.py` | LTX-Video generation |
| `nodes_lt_audio.py` | LTX-Video with audio |
| `nodes_lt_upsampler.py` | LTX-Video upsampling |
| `nodes_cosmos.py` | NVIDIA Cosmos video |

**Audio:**

| Node File | Purpose |
|---|---|
| `nodes_audio.py` | Load/save/preview audio |
| `nodes_audio_encoder.py` | Audio encoding to embeddings |
| `nodes_ace.py` | ACE audio generation model |

**3D:**

| Node File | Purpose |
|---|---|
| `nodes_load_3d.py` | Load 3D model files |
| `nodes_stable3d.py` | Stable3D generation |
| `nodes_hunyuan3d.py` | Hunyuan3D generation |

**Specialized Models:**

| Node File | Purpose |
|---|---|
| `nodes_flux.py` | Flux-specific conditioning/sampler nodes |
| `nodes_sd3.py` | SD3 triple conditioning |
| `nodes_pixart.py` | PixArt Sigma support |
| `nodes_hidream.py` | HiDream model support |
| `nodes_lumina2.py` | Lumina2 model support |
| `nodes_controlnet.py` | ControlNet + T2I adapter |
| `nodes_photomaker.py` | PhotoMaker identity preservation |
| `nodes_ip2p.py` | InstructPix2Pix editing |
| `nodes_upscale_model.py` | ESRGAN and super-resolution |
| `nodes_sdupscale.py` | SD upscale (latent upscale with re-diffusion) |
| `nodes_model_merging.py` | Checkpoint merging (add, merge, sequential) |

**Utilities:**

| Node File | Purpose |
|---|---|
| `nodes_string.py` | String manipulation |
| `nodes_math.py` | Math operations |
| `nodes_logic.py` | Conditional logic |
| `nodes_primitive.py` | Primitive value nodes |
| `nodes_torch_compile.py` | torch.compile integration |
| `nodes_glsl.py` | GLSL shader nodes |
| `nodes_webcam.py` | Webcam input |
| `nodes_rope.py` | RoPE (Rotary Position Embedding) |
| `nodes_easycache.py` | Easy cache management |

---

### 4.5 Workflow Blueprints

ComfyUI ships with 38 built-in blueprint workflows accessible from the **Templates** menu:

**Image Generation:**
- Text to Image
- Image to Image
- Image Inpainting
- Image Outpainting
- Depth to Image
- Canny to Image
- Pose to Image
- Image Upscale
- Image Edit

**Video:**
- Text to Video
- Image to Video
- Video Upscale
- Video Inpainting
- Video Stitching

**Audio:**
- Text to Audio

**3D:**
- Image to 3D Model

**Captioning & Prompting:**
- Image Captioning
- Video Captioning
- Prompt Enhancement

**Filters (Image):**
- Blur, Sharpen, Color Adjustment, Film Grain, Glow, and more

---

### 4.6 Saving and Loading Workflows

**Save (JSON):**
- `Ctrl+S` or Menu → Save Workflow
- Saves as `.json` to your local machine
- Workflows store the complete graph: node positions, connections, widget values

**Load:**
- `Ctrl+O` or Menu → Load Workflow
- Drag-and-drop a `.json` file onto the canvas
- Drag-and-drop a **PNG** that was generated by ComfyUI — the embedded workflow is extracted and loaded automatically

**Workflow JSON structure:**
```json
{
  "last_node_id": 10,
  "last_link_id": 12,
  "nodes": [...],
  "links": [...],
  "groups": [],
  "config": {},
  "extra": { "ds": { "scale": 0.8, "offset": [0, 0] } },
  "version": 0.4
}
```

---

### 4.7 The API — Programmatic Access

ComfyUI exposes a REST + WebSocket API on the same port as the UI.

**Submit a workflow:**

```python
# Based on script_examples/basic_api_example.py
import json, urllib.request

def queue_prompt(prompt_workflow):
    data = json.dumps({"prompt": prompt_workflow}).encode('utf-8')
    req = urllib.request.Request("http://127.0.0.1:8188/prompt", data=data)
    return json.loads(urllib.request.urlopen(req).read())

# Load your workflow JSON (in API format)
with open("my_workflow_api.json") as f:
    workflow = json.load(f)

# Change parameters by node ID
workflow["6"]["inputs"]["text"] = "a golden retriever puppy"  # node 6 = CLIP Text Encode
workflow["3"]["inputs"]["seed"] = 42  # node 3 = KSampler

result = queue_prompt(workflow)
print(result)  # {'prompt_id': 'abc123...', 'number': 1, 'node_errors': {}}
```

**WebSocket for live progress:**

```python
# Based on script_examples/websockets_api_example.py
import websocket, json, uuid

client_id = str(uuid.uuid4())
ws = websocket.WebSocket()
ws.connect(f"ws://127.0.0.1:8188/ws?clientId={client_id}")

# After queuing prompt, receive messages:
while True:
    out = ws.recv()
    if isinstance(out, str):
        message = json.loads(out)
        if message['type'] == 'progress':
            data = message['data']
            print(f"Step {data['value']}/{data['max']}")
        elif message['type'] == 'executing':
            if message['data']['node'] is None:
                print("Done!")
                break
```

> [!TIP]
> Export your workflow in **API format** (not the default graph format) before scripting. In the UI: Settings → Enable Dev Mode Options → then use the "Save (API Format)" button. The API format uses node IDs as keys, not human-readable names.

**Key API endpoints:**

| Method | Path | Description |
|---|---|---|
| `POST` | `/prompt` | Queue a workflow |
| `GET` | `/history` | Get all completed jobs |
| `GET` | `/history/{prompt_id}` | Get one job result |
| `GET` | `/queue` | Current queue status |
| `POST` | `/interrupt` | Cancel running job |
| `GET` | `/system_stats` | GPU/RAM info |
| `GET` | `/models/{type}` | List models of a type |
| `POST` | `/upload/image` | Upload an image to `input/` |
| `GET` | `/view?filename=...` | Download a result file |
| `GET` | `/object_info` | All node type definitions |

---

## 5. Common Tasks

### 5.1 Text to Image (Standard SD 1.5 / SDXL)

**Workflow overview:**

```
[Load Checkpoint]
    ↓ MODEL ──────────────────────────────────────────────────┐
    ↓ CLIP                                                     ↓
    ├─→ [CLIP Text Encode +] → CONDITIONING ──────────────→ [KSampler] → LATENT
    ├─→ [CLIP Text Encode -] → CONDITIONING ──────────────→                  ↓
    ↓ VAE                                                           [VAE Decode] → IMAGE
[Empty Latent Image] → LATENT ───────────────────────────→                         ↓
                                                                         [Save Image]
```

**Recommended settings for SDXL:**

```
Steps:     20–30
CFG:       5–8
Sampler:   euler_ancestral
Scheduler: karras
Size:      1024×1024 (or 1152×896, 896×1152 for landscape/portrait)
Denoise:   1.0
```

**Recommended settings for SD 1.5:**

```
Steps:     20–28
CFG:       7
Sampler:   euler_ancestral
Scheduler: karras
Size:      512×512 (or 512×768 for portrait)
Denoise:   1.0
```

---

### 5.2 Image to Image (img2img)

Replace `[Empty Latent Image]` with:

```
[Load Image] → IMAGE → [VAE Encode] → LATENT → [KSampler]
```

Set `denoise` in KSampler to `0.5–0.75` (lower = closer to original, higher = more creative).

**Denoise guide:**

| `denoise` | Effect |
|---|---|
| `0.2–0.3` | Subtle style/color changes, preserves composition |
| `0.4–0.6` | Moderate reinterpretation, similar composition |
| `0.7–0.85` | Heavy changes, loose resemblance to original |
| `0.9–1.0` | Near full generation, minimal original influence |

---

### 5.3 Inpainting

1. Load your source image with **Load Image**
2. Right-click the Load Image node → **Open in MaskEditor** — draw your mask
3. Use **VAE Encode (for Inpainting)** node (takes image + mask)
4. Use an inpainting-specific checkpoint (e.g., `sd-v1-5-inpainting.ckpt`)
5. Alternatively, use a standard model + **Differential Diffusion** nodes

```
[Load Image] → IMAGE ──────────────────────────────────────────→ [VAE Encode Inpaint] → LATENT
[Load Image] → MASK (drawn in MaskEditor) ──────────────────→ [VAE Encode Inpaint]
[Load Checkpoint] → MODEL, CLIP, VAE
[CLIP Text Encode] → CONDITIONING
[KSampler] (denoise 0.7–1.0) → [VAE Decode] → [Save Image]
```

---

### 5.4 Upscaling

**Workflow for 4x upscale:**

```
[Load Image] → IMAGE → [Upscale Image (using Model)] → IMAGE → [Save Image]
                              ↑
[Load Upscale Model] → UPSCALE_MODEL (from models/upscale_models/)
```

Popular upscale models for `models/upscale_models/`:
- `4x-UltraSharp.pth` — photorealistic details
- `4x_NMKD-Siax_200k.pth` — anime/illustration
- `RealESRGAN_x4plus.pth` — general purpose
- `RealESRGAN_x4plus_anime_6B.pth` — anime

For **latent upscaling** (allows re-diffusion for more detail):

```
[VAE Decode] → IMAGE → [Upscale Image] → IMAGE → [VAE Encode] → LATENT →
→ [KSampler (denoise 0.4)] → [VAE Decode] → [Save Image]
```

---

### 5.5 ControlNet (Guided Generation)

ControlNet constrains generation using a control image (depth map, edge map, pose skeleton, etc.):

```
[Load Image] → AIO Preprocessor → CONTROL_IMAGE ──────────────────────┐
[Load ControlNet Model] ────────────────────────────────────────────────┤
[CLIP Text Encode +] → CONDITIONING ────────────────────────────────────→ [Apply ControlNet] → CONDITIONING
```

Then feed the conditioned output to KSampler as the positive conditioning.

**Common ControlNet pairs:**

| Preprocessor | ControlNet Model | Use Case |
|---|---|---|
| Canny | `control_v11p_sd15_canny` | Edge-guided generation |
| DWPose / OpenPose | `control_v11p_sd15_openpose` | Pose-guided generation |
| Depth (Midas/Zoe) | `control_v11f1p_sd15_depth` | Depth-guided generation |
| Scribble | `control_v11p_sd15_scribble` | Sketch-to-image |
| Inpaint | `control_v11p_sd15_inpaint` | Inpainting with ControlNet |
| Normal map | `control_v11p_sd15_normalbae` | Surface normal guidance |
| SoftEdge | `control_v11p_sd15_softedge` | Softer edge guidance |
| Lineart | `control_v11p_sd15_lineart` | Lineart-to-image |
| Reference | (SDXL specific) | Style/pose reference |

**ControlNet strength (conditioning scale):**
- `0.3–0.5`: Subtle influence
- `0.6–0.8`: Moderate control
- `0.9–1.0`: Strong adherence to control image

---

### 5.6 LoRA Loading

Chain **Load LoRA** nodes between the checkpoint loader and the samplers:

```
[Load Checkpoint] → MODEL, CLIP
    → [Load LoRA] (lcm_lora, strength 1.0) → MODEL, CLIP
        → [Load LoRA] (detail_tweaker, strength 0.7) → MODEL, CLIP
            → [KSampler]
```

**LoRA strength guide:**

| `strength_model` | Effect |
|---|---|
| `0.3–0.5` | Subtle influence, preserves base model style |
| `0.6–0.8` | Moderate — good starting point |
| `0.9–1.0` | Full LoRA influence |
| `>1.0` | Over-application, may cause artifacts |

**Stacking LoRAs:** There's no hard limit, but each additional LoRA adds to VRAM usage and may conflict with others. Test incrementally.

---

### 5.7 Flux Workflows

Flux models use a different architecture: separate UNet + dual text encoders (CLIP-L + T5-XXL).

**Flux file placement:**
```
models/diffusion_models/flux1-dev.safetensors      ← or flux1-schnell.safetensors
models/clip/clip_l.safetensors
models/clip/t5xxl_fp16.safetensors                 ← or t5xxl_fp8_e4m3fn.safetensors
models/vae/ae.safetensors
```

**Flux workflow structure:**
```
[Load Diffusion Model] → MODEL → [ModelSamplingFlux] → [KSampler] → [VAE Decode]
[DualCLIPLoader] → CLIP → [CLIP Text Encode] → CONDITIONING (positive) → [KSampler]
                         → [CLIP Text Encode] → CONDITIONING (negative) → [KSampler]
[Load VAE] → VAE ────────────────────────────────────────────────────→ [VAE Decode]
[Empty SD3 Latent Image] → LATENT ──────────────────────────────────→ [KSampler]
```

**Recommended Flux settings:**

| Parameter | Flux Dev | Flux Schnell |
|---|---|---|
| Steps | 20–28 | 4 |
| CFG | 1.0 | 1.0 |
| Sampler | `euler` | `euler` |
| Scheduler | `simple` | `simple` |
| Resolution | 768²–1360×768 | Same |

> [!TIP]
> For Flux on limited VRAM (8–12 GB), use `t5xxl_fp8_e4m3fn.safetensors` instead of the fp16 T5 model. Run with `--fp8_e4m3fn-unet` and `--bf16-text-enc` to further reduce VRAM usage.

---

### 5.8 High-Resolution Fix (HiRes Fix)

For SD 1.5 models, generating at high resolution often causes quality issues. The standard solution is a two-pass workflow:

**Pass 1 — Base generation at training resolution:**
```
[Empty Latent Image] (512×512) → [KSampler] (denoise=1.0, 20 steps) → LATENT
```

**Pass 2 — Upscale latent + re-diffuse at target resolution:**
```
LATENT → [Latent Upscale] (to 1024×1024) → [KSampler] (denoise=0.5, 15 steps) → [VAE Decode] → [Save Image]
```

This is equivalent to A1111's "Hires. fix" and produces much better results than generating at 1024×1024 directly with SD 1.5.

---

### 5.9 Video Generation

ComfyUI supports multiple video generation models via built-in nodes.

**Supported video models:**

| Model Family | Node Category | Notes |
|---|---|---|
| Stable Video Diffusion (SVD) | `nodes_video_model.py` | img2vid, 14/25 frames |
| Wan 2.1 | `nodes_wan.py`, `nodes_wanmove.py` | txt2vid, img2vid |
| LTX-Video (LTXV) | `nodes_lt.py` | High-quality open-source video |
| Cosmos | `nodes_cosmos.py` | NVIDIA video model |
| Hunyuan Video | — | txt2vid, high quality |

**SVD img2vid example workflow:**

```
[Load Checkpoint] (SVD model) → MODEL, CLIP_VISION, VAE
[Load Image] → IMAGE → [ImageResize] → [SVD_img2vid_Conditioning] → CONDITIONING+/-
SVD_img2vid_Conditioning widgets: width, height, video_frames, motion_bucket_id, fps, augmentation_level
→ [KSampler] → LATENT → [VAE Decode] → IMAGE → [Video Combine] → video file
```

**Common SVD settings:**
```
video_frames: 14 (SVD) or 25 (SVD-XT)
motion_bucket_id: 127 (low motion) – 255 (high motion)
fps: 6–8
augmentation_level: 0.0
```

---

### 5.10 Audio Generation

ComfyUI supports text-to-audio and audio encoding workflows:

**Nodes for audio:**
- `nodes_audio.py` — core audio nodes (Load Audio, Save Audio, Preview Audio)
- `nodes_audio_encoder.py` — encode audio to embeddings for conditioning
- `nodes_ace.py` — ACE audio generation

Audio models go in `models/audio_encoders/`. Generated audio saves to `output/`. Supported formats: WAV, MP3, FLAC (read/write via `av>=14.2.0`).

---

### 5.11 3D Generation

**Image to 3D model** workflows use:
- `nodes_load_3d.py` — load 3D files (`.obj`, `.glb`, `.gltf`)
- `nodes_hunyuan3d.py` — Hunyuan3D 2.0 generation
- `nodes_stable3d.py` — Stable3D
- API nodes: Tripo, Rodin, Meshy, Luma (via external services)

Place 3D models in `models/` under their respective directories. Output 3D files save to `output/`.

---

### 5.12 Using API Nodes (External Services)

ComfyUI includes 32 built-in integrations with external AI services. These require API keys configured per-service.

**Available API node providers:**

| Provider | Capabilities |
|---|---|
| OpenAI | DALL-E image generation, GPT vision, Sora video |
| Stability AI | Stable Diffusion via API |
| BFL (Black Forest Labs) | Flux via API |
| Runway | ML video generation |
| Kling | Video generation |
| ElevenLabs | Text-to-speech |
| Luma | Video and 3D generation |
| Ideogram | Text-to-image |
| Google Gemini | Multimodal AI |
| Grok (xAI) | Text generation |
| Meshy | 3D model generation |
| Recraft | Vector/design generation |
| Topaz | AI upscaling and enhancement |
| MiniMax | Video generation |
| Wan (API) | Video generation |
| WaveSpeed | Accelerated video |
| HitPaw | Video enhancement |
| Veo2 (Google) | Video generation |
| PixVerse | Video generation |
| Magnific | AI upscaling |
| Rodin | 3D generation |
| Tripo | 3D generation |
| Hunyuan3D (API) | 3D generation |
| Bria | Background removal, image editing |
| ByteDance | Various AI services |
| Moonvalley | Video generation |
| Sonilo | Audio services |
| Reve | Image generation |
| Quiver | Various AI |
| Vidu | Video generation |
| LTXV (API) | LTX Video via API |

> [!NOTE]
> API nodes send your prompts and images to external servers. Review each provider's privacy policy before use. Disable all API nodes with `--disable-api-nodes` if you need fully local operation.

---

### 5.13 Batch Processing

**Queue multiple prompts:**
- Set "Batch count" in the Extra Options panel to queue N sequential runs
- Use the API to submit multiple `/prompt` requests programmatically

**Batch size vs. batch count:**

| Setting | Location | Behavior |
|---|---|---|
| `batch_size` in Empty Latent Image | Node widget | Generates N images in a single GPU pass (uses N× VRAM per pass) |
| Batch count in UI | Extra Options panel | Queues N separate sequential jobs |

**Scripted batch example:**
```python
import json, urllib.request, random

with open("workflow_api.json") as f:
    workflow = json.load(f)

for i in range(10):
    workflow["3"]["inputs"]["seed"] = random.randint(0, 2**32)
    workflow["6"]["inputs"]["text"] = f"prompt variant {i}"
    data = json.dumps({"prompt": workflow}).encode()
    urllib.request.urlopen(urllib.request.Request("http://127.0.0.1:8188/prompt", data=data))
    print(f"Queued job {i+1}/10")
```

---

### 5.14 Multi-GPU Setup

With multiple NVIDIA GPUs:

```bash
# Use a specific GPU (by index)
python main.py --cuda-device 0

# Run two separate instances on different GPUs and ports
# Terminal 1:
python main.py --cuda-device 0 --port 8188

# Terminal 2:
python main.py --cuda-device 1 --port 8189
```

Each instance has its own queue and UI. Submit to different ports to load-balance across GPUs.

---

### 5.15 Model Merging

ComfyUI has built-in model merging via `nodes_model_merging.py`:

**ModelMergeSimple** — weighted sum of two models:
```
[Load Checkpoint A] → MODEL → [ModelMergeSimple] → MODEL → [KSampler]
[Load Checkpoint B] → MODEL → [ModelMergeSimple]
                                       ↑
                                ratio: 0.5 (50/50)
```

**Save merged model** with the **Save Checkpoint** node. Merged models save to `models/checkpoints/`.

---

## 6. Troubleshooting

### Error: `CUDA out of memory`

**Cause:** The model or batch size requires more VRAM than your GPU has available.

**Solution:**
1. Reduce resolution in the Empty Latent Image node (try 512×512 for SD 1.5, 768×768 for SDXL)
2. Add `--lowvram` or `--novram` to your launch command
3. Reduce batch size to 1
4. Use `--fp8_e4m3fn-unet` or `--fp16-unet` to reduce model VRAM footprint
5. Close other GPU-intensive applications
6. Use `--cpu-vae` to run the VAE decode on CPU if VRAM is exhausted after sampling

**Prevention:** Monitor VRAM with `nvidia-smi` before starting. Reserve headroom with `--reserve-vram 1.0`.

---

### Error: `NotImplementedError: Cannot copy out of meta tensor`

**Cause:** A PyTorch module is in "meta" device state — typically caused by certain model loading paths or incompatible model formats. Related to GitHub issue #13426.

**Solution:**
1. Update ComfyUI: `git pull && pip install -r requirements.txt`
2. Try loading the model with a different node type (e.g., **Load Diffusion Model** instead of **Load Checkpoint**)
3. Add `--disable-smart-memory` to bypass advanced memory management
4. Check if the model file is corrupted: re-download it

**Prevention:** Keep ComfyUI and PyTorch up to date. Avoid mixing model formats across incompatible node types.

---

### Error: `TypeError: Failed to fetch`

**Cause:** The frontend cannot reach the backend server. Related to GitHub issue #12700.

**Solution:**
1. Verify the server is running (check terminal for `Prompt server running on...`)
2. Check that you're accessing the correct URL and port
3. If using a custom `--port`, make sure the URL matches
4. If accessing from another machine, ensure `--listen 0.0.0.0` is set and the firewall allows the port
5. Check for port conflicts: `netstat -an | grep 8188`
6. Restart ComfyUI

**Prevention:** Use `--port` to avoid conflicts with other services.

---

### Error: `HTTP 403 Forbidden` after update

**Cause:** The updated version added stricter origin validation for cross-domain requests. Related to GitHub issue #13444.

**Solution:**
1. Access ComfyUI through its direct URL (`http://127.0.0.1:8188`) instead of through a reverse proxy
2. If behind a reverse proxy, ensure the proxy passes the correct `Host` header
3. Add `--enable-cors-header` if accessing from a different origin
4. If using a custom domain, check that the `Origin` header matches what ComfyUI expects

**Prevention:** When setting up a reverse proxy, always configure proper `Host` and `X-Forwarded-For` headers.

---

### Error: `Failed to save workflow draft`

**Cause:** The browser's local storage quota is exceeded, or the server cannot write to the user directory. Related to GitHub issue #13134.

**Solution:**
1. Clear browser storage for the ComfyUI origin (DevTools → Application → Storage → Clear)
2. Check that the `user/` directory is writable by the ComfyUI process
3. Check available disk space
4. Try a different browser

**Prevention:** Periodically export important workflows as `.json` files. Don't rely solely on auto-saved drafts.

---

### Error: `DEFAULT (EMPTY WORKFLOW)` shown instead of expected workflow

**Cause:** The workflow file failed to parse, or the stored workflow in `user/` is corrupted. Related to GitHub issue #13440.

**Solution:**
1. Use `Ctrl+O` to manually load your workflow `.json` file
2. Delete the corrupted stored workflow: remove `user/default/workflows/` contents
3. If you generated the image, drag-and-drop the output PNG onto the canvas to recover the embedded workflow

---

### Error: `SVD_img2vid_Conditioning: NoneType has no attribute 'encode_image'`

**Cause:** The checkpoint loaded for SVD does not include a CLIP Vision encoder, or the model file is an incompatible variant. Related to GitHub issue #6392.

**Solution:**
1. Ensure you're using an actual SVD checkpoint (`svd.safetensors` or `svd_xt.safetensors`), not a regular SD checkpoint
2. Download and place `clip_vision_g.safetensors` in `models/clip_vision/`
3. Use the **Load CLIP Vision** node explicitly and connect it to `SVD_img2vid_Conditioning`

---

### Error: `Torch Compile breaks quick cancel`

**Cause:** `torch.compile()` wraps functions in a way that interferes with ComfyUI's cancellation mechanism. Related to GitHub issue #11627.

**Solution:** Do not use `--fast` (which may trigger torch compile) when you need reliable cancellation. Let the current step complete before cancelling.

**Prevention:** Only enable `--fast` for long non-interactive batch jobs where cancellation is not needed.

---

### Error: `Float8_e4m3fn on MPS backend not supported`

**Cause:** Apple Silicon (MPS) does not support fp8 tensor operations. Related to GitHub issue #12202.

**Solution:** Do not use `--fp8_e4m3fn-unet`, `--fp8_e4m3fn-text-enc`, or `--fp8_e5m2-unet` on macOS. Use `--bf16-unet` or `--fp16-unet` instead.

---

### Error: `ModuleNotFoundError: No module named 'torch'`

**Cause:** PyTorch is not installed, or you're running in a different Python environment than where you installed it.

**Solution:**
```bash
# Verify which Python is being used
which python   # Linux/macOS
where python   # Windows

# Verify torch is importable
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

# If using a venv, activate it first
source venv/bin/activate   # Linux/macOS
venv\Scripts\activate.bat  # Windows
```

---

### Error: `RuntimeError: CUDA error: device-side assert triggered`

**Cause:** Invalid tensor values (NaN/Inf), often from mismatched precision settings or corrupted model weights.

**Solution:**
1. Remove `--fast` flag
2. Try `--force-fp32` to eliminate precision issues as a variable
3. Re-download the model file (check SHA256 hash)
4. Try `--deterministic` to get a more informative error traceback

---

### Error: `OSError: [Errno 98] Address already in use`

**Cause:** Port 8188 is already in use by another process.

**Solution:**
```bash
# Find the process using the port
lsof -i :8188        # Linux/macOS
netstat -ano | findstr 8188  # Windows

# Kill it, or use a different port
python main.py --port 8189
```

---

### Error: No checkpoints found / Model not appearing in dropdown

**Cause:** The model file is in the wrong directory, wrong format, or the directory scan hasn't run.

**Solution:**
1. Verify the file is in `models/checkpoints/` (not nested an extra level)
2. Check the file extension: `.safetensors` or `.ckpt` (not `.zip`, `.tar`, etc.)
3. Click the refresh button (↺) in the Load Checkpoint node's model dropdown
4. Restart ComfyUI — model directories are scanned on startup
5. If using `extra_model_paths.yaml`, verify the paths are correct and the file is valid YAML

---

### Warning: `xformers not installed`

**Cause:** xformers is not installed. This is just a warning, not an error — ComfyUI will fall back to another attention method.

**Solution (optional — install xformers):**
```bash
pip install xformers
```

Or use another fast attention method without xformers:
```bash
python main.py --use-pytorch-cross-attention
python main.py --use-flash-attention   # requires: pip install flash-attn
```

---

### Error: `CUDA not available`

**Cause:** PyTorch was installed without CUDA support (CPU-only build from PyPI).

**Solution:**
```bash
# Check current torch version
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
# If shows: True → CUDA works. If False → reinstall.

# Reinstall with CUDA support
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
```

---

### Error: `RuntimeError: Expected all tensors to be on the same device`

**Cause:** Some nodes or LoRAs are on a different device than the model (CPU vs GPU mismatch).

**Solution:**
1. Remove `--cpu-vae` if it's set and your VRAM allows it
2. Try `--gpu-only` to force everything to GPU
3. Check for custom nodes that may move tensors to CPU unexpectedly
4. Restart ComfyUI with `--disable-all-custom-nodes` to isolate if a custom node is the cause

---

### Error: Models reloading between every run (slow)

**Cause:** VRAM management is offloading models aggressively. Related to GitHub issues #13423, #13434.

**Solution:**
```bash
# Keep models in VRAM after use
python main.py --highvram

# Or cache more aggressively
python main.py --cache-classic --highvram

# On large enough GPU, keep everything on GPU
python main.py --gpu-only
```

**Prevention:** Use `--highvram` or `--gpu-only` if your VRAM allows it to avoid repeated load/unload cycles.

---

### Error: `Workflow validation error: Invalid node type`

**Cause:** The workflow references a custom node that isn't installed.

**Solution:**
1. Check the error — it names the missing node type
2. Search for a custom node extension that provides that node
3. Install the missing extension to `custom_nodes/`
4. Restart ComfyUI

---

### Error: Preview images not showing during generation

**Cause:** Preview method is set to `none` (default), or TAESD models are missing.

**Solution:**
```bash
# Option 1: Use fast latent preview (no extra files needed)
python main.py --preview-method latent2rgb

# Option 2: Use TAESD (requires files in models/vae_approx/)
# Download: taesd_decoder.pth, taesdxl_decoder.pth
python main.py --preview-method taesd

# Option 3: Auto-selects best available
python main.py --preview-method auto
```

---

### Error: Generated images are blurry / low contrast / gray

**Cause:** The VAE is running in fp16 mode and producing decode artifacts.

**Solution:**
```bash
python main.py --fp32-vae
```

Some VAE models (especially older ones) cannot reliably decode in fp16 without color/contrast artifacts. `--fp32-vae` uses more VRAM but produces correct output.

---

### Error: `ImportError` when loading a custom node

**Cause:** The custom node has a Python dependency that isn't installed.

**Solution:**
1. Read the custom node's README for its dependency list
2. Install dependencies:
   ```bash
   pip install -r custom_nodes/NodeName/requirements.txt
   ```
3. Restart ComfyUI

---

### Error: `PermissionError: [Errno 13] Permission denied`

**Cause:** ComfyUI cannot write to the output, temp, or user directories.

**Solution:**
```bash
# Fix permissions (Linux/macOS)
chmod 755 output/ temp/ user/ input/

# Or run with explicit directory flags pointing to writable locations
python main.py --output-directory /tmp/comfyui-output --user-directory /tmp/comfyui-user
```

---

### Error: Prompt queued but nothing happens

**Cause:** A required node input is not connected, the queue is paused, or a previous job crashed the worker.

**Solution:**
1. Check the Queue panel — is the queue paused?
2. Look at the terminal for error output from the previous run
3. Check for red-highlighted (error) nodes in the canvas — hover for details
4. Click **Clear Queue** then re-queue your prompt

---

### Error: `NaN` / black or solid-color output images

**Cause:** Numerical instability during sampling — often from extreme CFG values, mismatched model/VAE, or a corrupted checkpoint.

**Solution:**
1. Lower the CFG scale (try 7.0)
2. Ensure the VAE matches the checkpoint architecture (SD 1.5 VAE ↔ SD 1.5 checkpoint; SDXL VAE ↔ SDXL)
3. Try `--force-fp32` to eliminate half-precision underflow
4. Re-download the checkpoint and verify its hash

---

### Error: ComfyUI not accessible from another machine on LAN

**Cause:** ComfyUI is only listening on `127.0.0.1` (localhost) by default.

**Solution:**
```bash
python main.py --listen 0.0.0.0
```

Then access via `http://<your-machine-IP>:8188`. Ensure your firewall allows port 8188.

> [!CAUTION]
> Binding to `0.0.0.0` exposes ComfyUI to your entire network with no authentication. Only do this on trusted networks. See the Admin Guide for reverse proxy + authentication setup.

---

### Error: `SSLError` / Certificate errors when using HTTPS

**Cause:** Self-signed certificate not trusted by browser, or certificate/key file mismatch.

**Solution:**
1. Trust the certificate in your browser (accept the warning, or add to trusted certificate store)
2. Verify the key and cert files are a matched pair:
   ```bash
   openssl x509 -noout -modulus -in cert.pem | md5sum
   openssl rsa -noout -modulus -in key.pem | md5sum
   # Both MD5 hashes should match
   ```
3. Check file paths passed to `--tls-keyfile` and `--tls-certfile`

---

### Error: `RuntimeError: Expected size ... got size ...` during sampling

**Cause:** Model and latent image size mismatch — e.g., using a 512-trained model with a 1024 latent.

**Solution:**
- SD 1.5 models: use 512×512 or 512×768 (multiples of 64, 8× factor)
- SDXL models: use 1024×1024 or multiples of 64 in that range
- Flux models: any size that is a multiple of 16

---

### Error: Slow startup / Long model scan time

**Cause:** Large number of model files causing slow SHA256 hashing on startup.

**Solution:**
```bash
# Use a faster hash algorithm
python main.py --default-hashing-function md5

# Or skip memory mapping if that's the bottleneck
python main.py --disable-mmap
```

---

### Error: `custom_nodes/[NodeName]` fails to load

**Cause:** Custom node was written for an older ComfyUI API, or has a Python syntax error.

**Solution:**
1. Check the terminal — Python tracebacks from custom node failures are printed with the node name
2. Update the custom node (often fixes compatibility issues)
3. Temporarily disable it by renaming the folder (e.g., `NodeName.disabled`)
4. Use `--disable-all-custom-nodes` to verify a clean ComfyUI baseline
5. Use `--whitelist-custom-nodes FolderA FolderB` to load only specific nodes

---

### Error: `Preview as Text` node showing wrong output

**Cause:** The Preview Any node renders certain data types incorrectly in some versions. Related to GitHub issue #13439.

**Solution:**
1. Update ComfyUI: `git pull && pip install -r requirements.txt`
2. Use the **Preview Image** node instead for image outputs
3. For text outputs, connect to the **Show Text** node or log to console with a Print node

---

### Error: `KeyError: 'ckpt_name'` or similar widget error

**Cause:** A node's widget value refers to a model file that no longer exists at the saved path.

**Solution:**
1. Click the affected node's model dropdown and select the correct file
2. Or refresh the model list (↺ button in the node) and re-select

---

### Error: Slow generation after memory management issues

**Cause:** Repeated load/unload cycles when VRAM fills up between runs. Related to GitHub issues #13423, #13434.

**Solution:**
```bash
# If you have enough VRAM (12+ GB):
python main.py --highvram --cache-classic

# If running lower VRAM, reduce RAM pressure with LRU cache:
python main.py --cache-lru 3
```

---

## 7. FAQ

**Q: What GPU do I need to run ComfyUI?**

Any NVIDIA GPU with 4+ GB VRAM can run SD 1.5 models using `--lowvram`. SDXL comfortably requires 8 GB. Flux requires 12–16 GB for fp16, or 8 GB with fp8 quantization. AMD GPUs work via ROCm (Linux) or DirectML (Windows). Apple Silicon M-series chips work via MPS. CPU-only is possible but extremely slow.

---

**Q: Does ComfyUI work on Windows without WSL?**

Yes. ComfyUI runs natively on Windows with a standard Python 3.10+ installation. The standalone `.7z` download includes everything pre-bundled. No WSL, no Linux required.

---

**Q: What's the difference between a checkpoint and a diffusion model?**

A **checkpoint** (`.safetensors`, `.ckpt`) contains the complete model: UNet/diffusion model + text encoder (CLIP) + VAE, all bundled in one file. A **diffusion model** is just the UNet component — used when you want to combine components manually (e.g., Flux workflows use a separate diffusion model + separate CLIP + separate VAE). Use `Load Checkpoint` for bundled files; use `Load Diffusion Model` for separate UNet files.

---

**Q: What's the correct directory for Flux models?**

Flux uses multiple separate files. Place them as follows:
```
models/diffusion_models/flux1-dev.safetensors
models/clip/clip_l.safetensors
models/clip/t5xxl_fp16.safetensors
models/vae/ae.safetensors
```

Use `Load Diffusion Model`, `DualCLIPLoader`, and `Load VAE` nodes — not `Load Checkpoint`.

---

**Q: How do I use models from Automatic1111 without copying files?**

Configure `extra_model_paths.yaml` to point at A1111's model directories. See [Section 3.2](#32-extra_model_pathsyaml--sharing-models-across-tools) for the full YAML example.

---

**Q: What is a workflow and how do I share one?**

A workflow is a JSON file that describes the complete node graph — all nodes, their connections, positions, and widget values. Export via `Ctrl+S`. Share the `.json` file. Recipients load it with `Ctrl+O` or by drag-and-drop onto the canvas. Generated PNGs also embed the workflow and can be dragged onto the canvas to load it.

---

**Q: What does CFG scale do?**

CFG (Classifier-Free Guidance) scale controls how strongly the sampler follows your text prompt. Low values (1–4): creative, may loosely interpret the prompt. Medium values (5–10): balanced — most use cases. High values (12–20): very literal, may over-saturate or produce artifacts. Flux models effectively ignore CFG — set it to 1.0.

---

**Q: Why does changing the seed produce a completely different image?**

Each seed initializes a different random noise pattern that gets denoised into an image. The seed is the primary source of variation at equal settings. Two images with different seeds but identical other settings explore different parts of the latent space. To reproduce an image exactly, use the same seed + same settings + `--deterministic`.

---

**Q: What is denoise strength?**

The `denoise` parameter in KSampler controls how much of the original latent is preserved. `1.0` = full generation from noise (text-to-image). `0.5` = roughly half the noise is added to an existing image, then removed (img2img). `0.2` = very light touch-up. Lower denoise = result closer to the original image.

---

**Q: How do I make ComfyUI accessible on my local network?**

```bash
python main.py --listen 0.0.0.0
```

Then connect from other devices at `http://[your-PC-IP]:8188`. Only do this on trusted networks — there is no built-in authentication by default.

---

**Q: Can multiple users run ComfyUI at the same time?**

Yes. Start with `--multi-user` to give each browser session its own workspace. Multiple sessions can queue jobs simultaneously — they run sequentially on a shared GPU. For completely separate GPU queues, run multiple instances on different ports with `--cuda-device` and `--port`.

---

**Q: How do I install custom nodes?**

Manual installation:
```bash
cd custom_nodes/
git clone https://github.com/author/ComfyUI-SomeNode.git
pip install -r ComfyUI-SomeNode/requirements.txt
# Restart ComfyUI
```

Or use **ComfyUI Manager** (install once, then manage extensions via the UI).

---

**Q: What is ComfyUI Manager?**

ComfyUI Manager is a popular extension that adds a management UI for installing, updating, and removing custom nodes. It also identifies missing nodes for loaded workflows. Enable it with `--enable-manager` after installation:
```bash
cd custom_nodes/
git clone https://github.com/ltdrdata/ComfyUI-Manager.git
# Restart ComfyUI, then launch with:
python main.py --enable-manager
```

---

**Q: How do I speed up generation?**

Ordered by impact:
1. Use a faster sampler: `euler` or `dpmpp_2m` with fewer steps (15–20)
2. Use `--highvram` or `--gpu-only` to avoid model reload between runs
3. Enable `--cache-classic` for iterative editing sessions
4. Install xformers or use `--use-flash-attention` (requires `pip install flash-attn`)
5. Use `--fast` to enable fp8 matrix multiply and CUDA optimizations (NVIDIA Ampere+)
6. Use fp8 quantized models (`--fp8_e4m3fn-unet`) for dramatic VRAM and speed gains
7. Use `--async-offload` (auto-enabled on NVIDIA; tune with `--async-offload 4`)

---

**Q: What is the difference between `--lowvram`, `--novram`, and `--cpu`?**

- `--lowvram`: Splits the UNet into parts and processes them sequentially, keeping only one part on GPU at a time. VRAM usage: ~4–6 GB for SD 1.5.
- `--novram`: Runs UNet weights from CPU memory, only moving tensors to GPU for computation. Slower than lowvram. VRAM usage: ~2–4 GB.
- `--cpu`: No GPU at all — all computation on CPU. Very slow (minutes per step). Only for testing or when no GPU is present.

---

**Q: Can I run ComfyUI without internet access?**

Yes. ComfyUI is fully local. The frontend package is downloaded once on first run and cached. After that, no internet is needed. The only internet-connected features are the optional API nodes (external services) and the Comfy cloud API. Disable them with `--disable-api-nodes`.

---

**Q: What is a LoRA and how is it different from a checkpoint?**

A **LoRA** (Low-Rank Adaptation) is a small auxiliary file (~10–300 MB) that modifies an existing checkpoint's behavior without replacing it. It adds style, subjects, or concepts on top of the base model. A checkpoint is a complete model (2–7 GB+). Apply LoRAs by inserting **Load LoRA** nodes in your workflow — multiple LoRAs can be stacked.

---

**Q: How do I use textual inversions / embeddings?**

Place `.pt` or `.safetensors` embedding files in `models/embeddings/`. Reference them in prompts using the filename (without extension):

```text
# In positive prompt:
a portrait of subject, <my_embedding>

# In negative prompt (to apply a negative embedding):
EasyNegative, bad anatomy, watermark
```

---

**Q: What is TAESD and why do I need it for previews?**

TAESD (Tiny AutoEncoder for Stable Diffusion) is a lightweight decoder that converts latent tensors to viewable images quickly — much faster than a full VAE decode. It enables real-time previews during the denoising steps. Download files and place in `models/vae_approx/`:
- `taesd_decoder.pth` — SD 1.5
- `taesdxl_decoder.pth` — SDXL
- `taesd3_decoder.pth` — SD3/Flux

Then launch with `--preview-method taesd` or `--preview-method auto`.

---

**Q: How do I export a video generated in ComfyUI?**

Video workflows use the **Video Combine** node, which writes the output as MP4, WebM, or GIF to `output/`. The file appears automatically in the output directory. Configure format, frame rate, and quality in the Video Combine node's widgets.

---

**Q: What is `--fast` and is it safe to use?**

`--fast` enables NVIDIA-specific performance optimizations:
- `fp16_accumulation`: accumulate in fp16
- `fp8_matrix_mult`: use fp8 for matrix multiplications
- `cublas_ops`: use cuBLAS optimized operations
- `autotune`: auto-tune CUDA kernels for your GPU

These provide 10–30% speedups on NVIDIA Ampere+ (RTX 3000+). Minor quality changes are possible. Torch.compile interference with quick-cancel is a known issue — see Troubleshooting.

---

**Q: How do I enable HTTPS?**

```bash
# Generate a self-signed cert (for local use):
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Launch with HTTPS:
python main.py --tls-keyfile key.pem --tls-certfile cert.pem
# Access at: https://127.0.0.1:8188
```

For a public server, use a CA-signed certificate. See the Admin Guide for full reverse proxy setup.

---

**Q: What file formats does ComfyUI read/write?**

| Direction | Formats |
|---|---|
| Input images | PNG, JPEG, WebP, BMP, TIFF |
| Output images | PNG (default), JPEG, WebP |
| Models | `.safetensors` (preferred), `.ckpt`, `.pt`, `.pth`, `.bin` |
| Workflows | `.json` |
| Output video | MP4, WebM, GIF |
| Output audio | WAV, MP3, FLAC |

---

**Q: How do I recover a workflow from a generated PNG?**

Drag the PNG file directly onto the ComfyUI canvas. If the file was generated by ComfyUI (with metadata enabled), the workflow is extracted and loaded automatically.

To disable metadata embedding (for privacy): `python main.py --disable-metadata`.

---

**Q: Can I run ComfyUI as a system service?**

Yes. See the Admin Guide for systemd (Linux) and Windows Service setup. Key considerations: run as a non-root user, set explicit directory paths with `--base-directory`, and use `--dont-print-server` for clean logging.

---

**Q: What is the difference between sampler and scheduler?**

The **sampler** determines the mathematical algorithm used to move from noise toward the final image (Euler, DPM++, DDIM, etc.). The **scheduler** determines how the noise level decreases across the steps (karras, exponential, simple, etc.). They work together: a sampler + scheduler combination defines the complete denoising trajectory. The `karras` scheduler generally produces sharper results; `simple` is the recommended default for Flux.

---

**Q: What is the `--database-url` flag for?**

ComfyUI uses a SQLite database (stored at `user/comfyui.db` by default) to persist user account data, settings, and API key management. The `--database-url` flag lets you point it at a different SQLite file or a PostgreSQL database for multi-server deployments.

---

**Q: What's the recommended workflow for Stable Diffusion 3.x?**

SD3 uses the same architecture split as Flux: separate diffusion model, three text encoders, and VAE. Use:
- `Load Diffusion Model` for the SD3 model
- `TripleCLIPLoader` for the three text encoders (CLIP-L, CLIP-G, T5-XXL)
- `Load VAE` for the SD3 VAE
- `Empty SD3 Latent Image` node for the latent
- `CLIPTextEncodeSD3` for the conditioning

---

**Q: Can ComfyUI generate images at any resolution?**

Yes, with caveats:
- SD 1.5 models were trained at 512×512. Higher resolutions cause compositional issues. Use HiRes Fix (img2img pass at lower denoise) for larger outputs.
- SDXL was trained at 1024×1024. Works well from 768×768 to 1536×1024.
- Flux supports a wide range of resolutions natively.
- All resolutions must be multiples of 64 (SD family) or 16 (Flux family).

---

**Q: What is the difference between `models/unet/` and `models/diffusion_models/`?**

These directories serve the same purpose: standalone UNet/diffusion model files (not full checkpoints). The naming reflects different naming conventions in the community. ComfyUI treats them equivalently — use whichever name matches how you downloaded the file. For Flux, `diffusion_models/` is the conventional location.

---

**Q: How do I check what version of PyTorch and CUDA I'm running?**

```python
python -c "import torch; print('PyTorch:', torch.__version__); print('CUDA:', torch.version.cuda); print('GPU:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'N/A')"
```

---

## Reference Tables

### Sampler × Scheduler — Quick Reference

| Use Case | Sampler | Scheduler | Steps | CFG |
|---|---|---|---|---|
| SD 1.5 — quality | `euler_ancestral` | `karras` | 20–28 | 7 |
| SD 1.5 — speed | `dpmpp_2m` | `karras` | 15–20 | 7 |
| SDXL — quality | `euler_ancestral` | `karras` | 20–30 | 6 |
| SDXL — speed | `dpmpp_2m` | `karras` | 15 | 6 |
| Flux dev | `euler` | `simple` | 20–28 | 1 |
| Flux schnell | `euler` | `simple` | 4 | 1 |
| LCM | `lcm` | `lcm` | 4–8 | 1–2 |
| Lightning | `euler` | `sgm_uniform` | 4–8 | 1 |
| Reproducible | `euler` | `normal` | 20 | 7 |
| SD3 | `euler` | `sgm_uniform` | 28 | 5 |

---

### VRAM Usage Estimates

| Model | Precision | Approx. VRAM |
|---|---|---|
| SD 1.5 checkpoint | fp16 | ~2 GB |
| SDXL checkpoint | fp16 | ~6.5 GB |
| SDXL inference peak (1024²) | fp16 | ~10–12 GB |
| Flux UNet only | fp16 | ~24 GB |
| Flux UNet only | fp8 | ~12 GB |
| T5-XXL (Flux text encoder) | fp16 | ~9 GB |
| T5-XXL (Flux text encoder) | fp8 | ~5 GB |
| TAESD decoder | — | ~50 MB |
| ControlNet | fp16 | ~1–2 GB additional |

---

### Keyboard Shortcuts — Full Reference

| Shortcut | Action |
|---|---|
| `Ctrl+Enter` | Queue prompt |
| `Ctrl+S` | Save workflow |
| `Ctrl+O` | Open workflow |
| `Ctrl+Z` | Undo |
| `Ctrl+Y` | Redo |
| `Ctrl+A` | Select all nodes |
| `Ctrl+C` | Copy selected |
| `Ctrl+V` | Paste |
| `Ctrl+B` | Bypass/enable node toggle |
| `Ctrl+G` | Group selected nodes |
| `Ctrl+P` | Pin/unpin node |
| `Delete` / `Backspace` | Delete selected |
| `F` | Fit canvas to all nodes |
| `Double-click canvas` | Open node search popup |
| `Right-click node` | Node context menu |
| `Scroll wheel` | Zoom canvas |
| `Space + drag` | Pan canvas |
| `Middle-click drag` | Pan canvas |

---

### Model Format Compatibility

| Format | Extension | Load with | Notes |
|---|---|---|---|
| SafeTensors | `.safetensors` | Any loader | Preferred. Fast, safe, no arbitrary code execution. |
| PyTorch checkpoint | `.ckpt` | Load Checkpoint | Older format. Executes Python on load (security risk with untrusted files). |
| PyTorch | `.pt`, `.pth` | Varies | LoRAs, embeddings, upscale models |
| Binary | `.bin` | Varies | HuggingFace serialization format |
| Diffusers | directory | Load Checkpoint | HuggingFace Diffusers format |

---

### Node Color Reference

| Data Type | Color | Common Sources | Common Destinations |
|---|---|---|---|
| `MODEL` | Gold/yellow | Load Checkpoint, Load Diffusion Model | KSampler, Apply ControlNet |
| `CLIP` | Teal/cyan | Load Checkpoint, DualCLIPLoader | CLIP Text Encode |
| `VAE` | Purple | Load Checkpoint, Load VAE | VAE Encode, VAE Decode |
| `CONDITIONING` | Pink/magenta | CLIP Text Encode | KSampler (positive/negative) |
| `LATENT` | Light blue | Empty Latent Image, VAE Encode | KSampler, VAE Decode |
| `IMAGE` | Orange | Load Image, VAE Decode | Save Image, VAE Encode |
| `MASK` | Green | Load Image, Mask Editor | VAE Encode Inpaint |
| `CONTROL_NET` | Red | Load ControlNet Model | Apply ControlNet |
| `UPSCALE_MODEL` | — | Load Upscale Model | Upscale Image (using Model) |
| `CLIP_VISION` | — | Load CLIP Vision | SVD Conditioning, IP-Adapter |

---

*For infrastructure, API endpoints, deployment, architecture internals, and operational configuration — see the ComfyUI Admin Guide at [Admin Guide](/guides/Comfy-Org/ComfyUI/admin-guide/).*

---

_Generated May 2026 from Comfy-Org/ComfyUI at c033bbf. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._