Iris-3B GGUFs — Rebel AI

Quantized Iris-3B diffusion checkpoints for local image generation in ComfyUI.

Iris-3B is a 3-billion-parameter pixel-space diffusion transformer: it generates image pixels directly instead of using a VAE or a latent decoder.

ComfyUI custom nodes: RealRebelAI/ComfyUI-Iris-3B

Development status: The standard/W4A8 ComfyUI pipeline has produced clean 1024×1024 outputs. The new GGUF-specific loader and sampler are experimental; GPU inference, quality, and memory use have not yet been verified for every quantization. These GGUFs are diffusion-model weights, not standalone models for llama.cpp or general-purpose LLM runtimes.

Available checkpoints

Smaller weight files can reduce the model-weight memory footprint, but do not guarantee a given VRAM requirement. Pixel-space image activations and Qwen3-VL text encoding also consume memory. Quality/performance comparisons have not yet been independently validated across all GGUF variants.

Install for ComfyUI

You only need one Iris custom-node installation. The GGUF-specific nodes are included inside that repository and register automatically. You do not install gguf_addon/ as a separate Iris custom-node folder.

1. Install or update Rebel AI's Iris nodes

Clone ComfyUI-Iris-3B into ComfyUI/custom_nodes/, or update your existing copy. If you already have a working W4A8/full-weight installation, back up nodes.py and do not overwrite it with untested sampler changes. The GGUF additions only need the updated main __init__.py and the included gguf_addon/ folder.

Your Iris custom-node folder should contain:

ComfyUI/custom_nodes/ComfyUI-Iris3B/
├── __init__.py               # Registers both standard and GGUF nodes
├── nodes.py                  # Existing FP32 / W4A8 sampler
├── gguf_addon/
│   ├── __init__.py
│   └── gguf_nodes.py         # Dedicated experimental GGUF loader/sampler
├── install_iris_source.py
└── third_party/
    └── iris-3b/
        └── src/
            └── iris3b/      # Official source installed here

If the official Iris source isn't installed yet, run install_iris_source.py once using ComfyUI's own Python environment, not another system Python. The Qwen3-VL-4B-Instruct text encoder is separately required and will be downloaded by Transformers on first use if not already cached.

2. Install the GGUF backend

Install city96/ComfyUI-GGUF separately as a sibling of the Iris node folder. Its dependencies, including the GGUF Python library, must be available in ComfyUI's Python environment.

ComfyUI/custom_nodes/
├── ComfyUI-Iris3B/          # One Iris installation; addon is INSIDE it
└── ComfyUI-GGUF/            # Separate city96 GGUF backend

The external GGUF backend is required only for GGUF inference, not for the original FP32/W4A8 workflow.

3. Put the checkpoint in the correct models folder

Download your chosen .gguf from this repository into the normal ComfyUI checkpoints folder, preferably under an Iris-3B subfolder:

ComfyUI/
└── models/
    └── checkpoints/
        └── Iris-3B/
            ├── Iris-3B-Q3_K_S.gguf
            ├── Iris-3B-Q4_K_S.gguf
            ├── Iris-3B-Q5_K_S.gguf
            └── Iris-3B-Q6_K.gguf

Example Windows portable location:

D:\AI_Tools\ComfyUI_windows_portable\ComfyUI\models\checkpoints\Iris-3B\

The Iris-3B folder is optional organization; the dedicated checkpoint node searches ComfyUI's configured checkpoints paths, including their subfolders. Do not put .gguf weights inside custom_nodes/.

4. Restart and assemble the GGUF workflow

Fully restart ComfyUI after updating the custom nodes. Search for these two dedicated nodes:

• Iris 3B GGUF Checkpoint
• Iris 3B GGUF Sampler (Experimental)

Both nodes should appear even before a GGUF checkpoint has been added. To generate:

Iris 3B GGUF Checkpoint ───┬──> Iris 3B Qwen3-VL Encode
                           │                  │
                           │             conditioning
                           │                  │
                           └──> Iris 3B GGUF Sampler (Experimental) ──> Save Image

Connect the GGUF checkpoint output to both the existing Iris 3B Qwen3-VL Encode node and the dedicated GGUF sampler. Connect the encoder's conditioning output to the GGUF sampler's conditioning input.

Reference settings: 1024×1024, 100 steps, CFG 3.0, shift 4.0, order 2, BF16 dequant/autocast. These are the original model's approximate generation defaults, not a guarantee of speed or quality in the experimental GGUF path.

W4A8 / full-weight files use the original nodes

The Iris-3B-W4A8.safetensors file does not go through the GGUF sampler. Use the standard Iris 3B Checkpoint, Iris 3B Qwen3-VL Encode, and Iris 3B Sampler nodes. The new GGUF node registration does not need to replace the proven W4A8/full-weight inference code.

Image editing, restoration, and depth

These GGUF files represent Iris's base text-to-image diffusion model. They do not implement prompt-driven image editing. The original SperiLabs release provides separate, fine-tuned checkpoints for image restoration/upscaling and depth estimation. Those tasks require their corresponding weights and inference implementations; they should not be advertised as features of the base GGUF checkpoint.

See SperiLabs' original model card for those tasks.

Troubleshooting

• No GGUF node in search: update the main Iris repository, confirm gguf_addon/ is nested inside it and __init__.py is the latest version, then fully restart ComfyUI. Missing checkpoint files are not what prevents these two node names from appearing.
• GGUF node shows, but no model in the dropdown: put a .gguf file under ComfyUI/models/checkpoints/ (or a subfolder) and refresh/restart ComfyUI.
• GGUF dependency missing when sampling: ensure ComfyUI-GGUF/ is separately installed alongside the Iris folder and its Python dependencies are installed.
• W4A8 or FP32 model: select the regular Iris sampler, not the dedicated GGUF sampler.
• CUDA out of memory: smaller weights do not eliminate pixel-space activation memory; lowering steps does not proportionally lower peak VRAM. Use compatible ComfyUI memory options and avoid assuming every GGUF fits every GPU.

Please report reproducible GGUF issues in the GitHub issue tracker, including your GGUF filename, ComfyUI version, GPU, and the relevant error message.

Credits and licensing

Original architecture, model weights, research, and training: SperiLabs / Iris-3B — Apache 2.0.

Quantized GGUF/W4A8 weights and ComfyUI integration: Rebel AI.

ComfyUI GGUF backend: city96/ComfyUI-GGUF.

This repository contains derivative quantizations of the upstream model. Refer to the original model card for limitations and research citations.