Checkpoint Loader (GGUF) ⚡

Why this node exists

Stock Load Checkpoint doesn't list .gguf files. Not "loads them badly" - doesn't show them at all. So unless your file is a single-file all-in-one checkpoint, you end up with three nodes doing one job: UNET Loader (GGUF) for the model, a CLIP Loader (GGUF) for the text encoder, a VAE Loader for the decoder.

Checkpoint Loader (GGUF) is that collapsed back into one node. One dropdown, three outputs, and it doesn't care whether the file is .safetensors or .gguf - the whole point for single-file checkpoints that carry their own text encoder and VAE, where splitting into three loaders is just busywork.

It ships inside ComfyUI-GGUF-Loader, a fork of city96's original ComfyUI-GGUF (Apache-2.0 - the loader, the quant tooling and the custom ops are city96's; the fork adds backported upstream PRs and newer architectures). If you're filing a bug, file it on the fork, not upstream.

What it actually does

The GGUF path isn't a reimplementation of checkpoint loading. It reads the file through this pack's GGUF state-dict loader, wraps the weights in the pack's GGMLOps custom operations so they stay quantized, and hands the state dict to ComfyUI's own comfy.sd.load_state_dict_guess_config - the function stock Load Checkpoint ends up in under the hood. That's deliberate: detection, CLIP construction and VAE construction come out matching a safetensors checkpoint, so the outputs are the stock ones, not a fork-flavoured approximation.

Two consequences worth knowing:

• GGUF stays quantized. Weights sit packed in their quant format and get dequantized on the fly inside the linear/conv layers at matmul time - that's what buys you the VRAM. The trade is dequantization overhead, and it's why LoRA-on-GGUF is slower than LoRA-on-fp8: every patched layer is dequantized, patched and requantized. The MODEL comes back wrapped in the pack's GGUFModelPatcher, which is what makes that path work on packed weights at all.
• If the format can't carry the config, a sidecar has to. GGUF can't hold a transformer-config JSON the way safetensors can, so for split checkpoints the loader merges <your-file>-metadata.json - or a folder-level *metadata*.json that names this exact file - into the metadata. Skip it and detection can build a plausible-looking model with the wrong block count that dies deep in the forward instead of at load. Name the sidecar after the checkpoint; two sidecars claiming one file and it refuses to guess.

The input and the outputs

One required input, ckpt_name. The tooltip is the author's: a .safetensors or .gguf checkpoint from models/checkpoints, or a UNET GGUF. The dropdown merges several folders, so what shows up is:

models/checkpoints/          .safetensors, .ckpt   (stock key)
models/checkpoints/          .gguf                 (this pack adds the key)
models/diffusion_models/     .gguf                 (unet)
models/unet/                 .gguf

Outputs are named exactly like stock Load Checkpoint, so this is a drop-in swap in an existing graph:

• model → KSampler / SamplerCustom
• clip → CLIPTextEncode
• vae → VAE Decode / VAE Encode

Installing it

Search ComfyUI-GGUF-Loader in ComfyUI Manager (the pack is on the Comfy Registry under publisher chriscoletech), or clone it by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/ChrisColeTech/ComfyUI-GGUF-Loader
pip install --upgrade gguf

Standalone Windows portable build:

git clone https://github.com/ChrisColeTech/ComfyUI-GGUF-Loader ComfyUI/custom_nodes/ComfyUI-GGUF-Loader
.\python_embeded\python.exe -s -m pip install -r .\ComfyUI\custom_nodes\ComfyUI-GGUF-Loader\requirements.txt

The README says gguf is the only dependency for inference, and that's true - requirements.txt also lists sentencepiece, protobuf, timm, requests and qwen-tts for other nodes in the pack, so a minimal pip install --upgrade gguf is genuinely enough here.

One caution: this fork registers the same GGUF loader class names as city96's original pack. Run both and you get duplicate menu entries with no obvious way to tell which pack's loader you dragged in. Pick one.

Where people get burned

You loaded a UNET-only GGUF and clip came back empty. This node returns MODEL, CLIP and VAE because all-in-one files have all three inside them. A plain flux1-dev-Q4_K_M.gguf has no text encoder and no VAE in it. ComfyUI builds the model, logs "no CLIP/text encoder weights in checkpoint", and hands you a None CLIP plus an empty placeholder VAE that raises the moment anything uses it. That's not a broken node, it's the wrong node - use UNET Loader (GGUF) plus separate CLIP and VAE loaders for split component files.

The file exists but isn't in the dropdown. It has to live in one of the folders above. models/checkpoints only accepts .gguf through the extra folder key this pack registers. It's the single most common GGUF confusion in the wild.

Older ComfyUI. Loading a UNET-only GGUF needs a ComfyUI recent enough to support custom ops. Update before hunting for a bug in the node. And on MacOS Sequoia, the README passes along the upstream workaround: torch 2.4.1, because 2.6.x nightlies throw "M1 buffer is not large enough".

Wrong quant for the wrong reason. Q8 is essentially fp16 at half the size and Q4_K_M is the accepted 12GB compromise, but if your model already fits at fp8, quantizing further mostly buys you dequantization overhead. Reach for Q4 when you're out of VRAM, not as a default.