FLUX 3 PE GGUF (T8)

FLUX 3 PE GGUF · T8

English | 简体中文

Local prompt enhancement for ComfyUI, powered by Black Forest Labs' FLUX 3 Image Klein PUP and a Q4_K_M GGUF backend. Turn short requests, reference images and layout boxes into detailed prompts for FLUX 3 workflows.

Models · Runtime downloads · Workflow preview

v0.2.3: Official PUP and Heretic PUP Q4_K_M are available on Hugging Face, with matching projectors, manifests and SHA256 checksums. This release updates model distribution and documentation; inference code and workflows are unchanged from the validated v0.2.2.

Features

• Text enhancement, reference-image editing instructions and both layout modes.
• Up to 10 reference images, with explicit image order and locked object boxes.
• STRING output for text encoders, configurable result caching and a maximum of one recovery attempt.
• Direct inference with an installed llama-cpp-python wheel, including reference images; no separate server executable is needed for this backend.
• PE memory release before image generation with keep_loaded=false.

Installation

Requires Python 3.10+ and a recent ComfyUI with the V3 node API. The Python-wheel backend uses the installed wheel and its platform-specific dependencies. The optional prebuilt server runtime targets Windows x64 / NVIDIA CUDA 13.4.

1. Install FLUX 3 PE GGUF (T8) through ComfyUI Manager when the Registry version is available, or clone into ComfyUI/custom_nodes:

   git clone https://github.com/T8mars/Comfyui-Flux3-PE-GGUF-T8.git ComfyUI-Flux3-PE
   

2. Use your ComfyUI Python to install requirements.txt.

3. Choose a model from the model repository. For official PUP, download all three files into the node folder's models/gguf/:

   | File | Size | |---|---:| | flux3-klein-pup-Q4_K_M.gguf | 5.63 GB | | mmproj-flux3-klein-pup-F16.gguf | 0.92 GB | | manifest.json | Small metadata file |

   For Heretic PUP, use the Heretic downloads and its separate heretic/ directory.

4. Install a compatible llama-cpp-python >=0.3.36, <0.4 wheel into the same Python that runs ComfyUI, then restart ComfyUI. An existing compatible installation can be reused. For example, with CUDA 13.2 runtime libraries and a compatible driver:

   python -m pip install --upgrade --only-binary=llama-cpp-python llama-cpp-python==0.3.36 --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu132
   

   Select the wheel matching your system below. The CPU index can be used without CUDA. GPU wheels require compatible CUDA libraries and drivers.

   On Windows, set CUDA_PATH to the compatible CUDA installation if its runtime libraries are not otherwise available. Version 0.2.1 loads the wheel's DLL dependencies directly; no external preload script is required.

   To use the original server backend, download flux3-pe-runtime-win-x64-cuda13.4.zip from v0.1.5 runtime downloads, extract it into the node folder, and select llama-server. Its executable should be at runtime/bin/llama-server.exe.

Model files stay outside Git and the Registry package. Enhancement runs locally; node execution does not upload prompts or reference images.

llama.cpp and Python wheels

• llama.cpp official binaries: standalone programs, including llama-server (llama-server.exe on Windows).
• llama-cpp-python GitHub releases and installation guide: Python bindings that can run inference without a separate server executable.
• Official wheel files: CPU · CUDA 12.4 · CUDA 13.2. Select a wheel matching your Python version, OS, architecture and CUDA requirements; see the installation guide for other builds.

Backend selection: auto prefers a compatible installed Python wheel and otherwise uses the packaged server if available. Select llama-cpp-python to require in-process inference, or llama-server for the original server backend. The wheel backend uses MTMD for reference images and a fresh native sampler to apply penalties only to generated tokens; it needs neither llama-server.exe nor flux3-pe-runtime.json. Python-wheel availability and acceleration depend on your OS and hardware; local GPU model validation used Windows x64 / CUDA 13.2, not Linux/macOS GPUs.

Usage

1. Add FLUX 3 PE Model (GGUF), select the Q4_K_M model, and leave backend=auto or select llama-cpp-python.
2. Connect it to FLUX 3 Prompt Enhancement and enter a prompt. Connect images in reference order when needed.
3. Connect enhanced_prompt to a text encoder or ComfyUI's Preview as Text. details_json reports timing, caching and recovery.

Leave keep_loaded=false when the next step generates an image. Disable use_cache to force a new enhancement.

Layout input uses normalized [y_min, x_min, y_max, x_max] coordinates:

[{"id":"balloon","desc":"a red balloon","bbox":[0.1,0.1,0.6,0.4]}]

For reference-image layouts, use from="ref_image_0", src_bbox and tgt_bbox. New objects use from="target" and src_bbox=null; removed objects use tgt_bbox=null.

Example workflows

Drag a JSON file from examples into ComfyUI:

• Text enhancement
• Layout enhancement
• PE → FLUX 3 image generation
• Two-reference editing instructions

To copy the example workflows and their reference images into your installation, run from the node folder:

& .\scripts\install_comfy.ps1 -ComfyUI 'C:\path\to\ComfyUI'

The image-generation example additionally requires FLUX 3 diffusion weights, its Qwen3-VL text encoder and FLUX.2 VAE. These are separate downloads.

Heretic PUP

Version 0.2.2 supports the pinned tuanlai/flux-3-image-klein-pup-heretic checkpoint. It uses the same four PE protocols, keeps separate model artifacts and reports its actual source in the details output.

Download these files together into models/gguf/heretic/ or ComfyUI/models/flux3_pe/heretic/:

| File | Size | |---|---:| | flux3-klein-pup-heretic-Q4_K_M.gguf | 5.63 GB | | mmproj-flux3-klein-pup-heretic-F16.gguf | 0.92 GB | | manifest.json | Source and SHA256 | | SHA256SUMS.txt | Download verification |

Or run this from the node folder with the Hugging Face CLI installed:

hf download t8star/Flux3-PE-GGUF-Comfy --include "heretic/*" --local-dir models/gguf

Keep the official model's manifest separate. Select heretic/flux3-klein-pup-heretic-Q4_K_M.gguf in the loader and use node version 0.2.2+.

• Heretic text enhancement
• Heretic layout enhancement
• Heretic PE → FLUX 3 image generation
• Heretic two-reference editing

The source repository provides BF16 and INT8 safetensors. For GGUF conversion, use its BF16 checkpoint as model.safetensors, together with the pinned official PUP configuration, tokenizer and image-processing files. Prepare the llama.cpp conversion tools using the development guide, then run this from a source checkout. The converter verifies the source SHA256:

python scripts/quantize.py --variant heretic --source "path/to/heretic-source" --output models/gguf/heretic --quants Q4_K_M

Pinned source-file revision: 80efba65e01bb2e320dea412fa657d701491b443. Protocol and configuration source: official PUP 8b069751eb5dcab23829d9c5eccb470eb8b8a4ed. See the source repository for the Heretic weights' license information.

Heretic Q4_K_M passed 40/40 real-model tasks, seven canvas executions, four workflow save/reopen checks and PNG workflow restoration, alongside 481 unit tests and six official-model regressions. The real-model checks used Windows / RTX 5090 Laptop / the Python-wheel backend. Validation record · Actual canvas preview

Validation and development

The 0.2.1 Python-wheel backend passed 470 unit tests, 40 real model structural/text-preservation cases in a clean Windows environment, and six real Linux CPU tasks covering all four PE modes, Chinese text and ten references. Seven real canvas executions, workflow save/reopen checks and PNG workflow restoration also passed. No external native-library preload script was used for these model or canvas checks. One Windows Chinese editing case used the bounded recovery path. These checks do not guarantee semantic correctness for every prompt.

Development, runtime build and benchmark notes

T8star links

Bilibili · YouTube · API · Free gallery

Online AI apps · ComfyUI bundle · Hugging Face

Credits and license

Node integration: T8star, Apache-2.0. Official PUP weights and reference code: Black Forest Labs, Apache-2.0. Heretic checkpoint: tuanlai; see its upstream license declarations. Inference: llama.cpp, MIT; the optional server runtime includes the sampling patch. CUDA libraries retain NVIDIA's license terms. See LICENSE, NOTICE and licenses.