feat(flux3): load quantized FLUX.3 single files

docs/src/content/docs/Users Guide/03.Models/02.model-families.mdx

@@ -47,9 +47,9 @@ InvokeAI recognizes the format from the file's contents, so you install them lik
 - **GGUF** (`.gguf`, llama.cpp quantization such as Q4_K or Q8_0): weights stay packed in memory and are unpacked layer by layer during generation. Supported for the FLUX.1, FLUX.2, FLUX.3, Z-Image, Krea-2, Qwen-Image, Qwen-Image-2.1, Ideogram 4, ERNIE-Image and Wan transformers, and for the T5, Qwen3, Qwen3-VL, Mistral and Gemma 2 text encoders. ComfyUI-GGUF's `Q8_CR` and `Q4_CR` files, which store int8 or int4 convrot layers inside a `.gguf`, load for the Krea-2 transformer; for other models installation is refused with a message saying so.
 - **NF4** (bitsandbytes): 4-bit, CUDA only.
 - **SDNQ**: see [SDNQ Quantization](/configuration/optimization/sdnq-quantization/).
-- **int8** (`int8_convrot`, from ComfyUI repackages): the weights stay int8 in memory on every device, including Apple Silicon, and need no setting to turn on. Supported for FLUX.1, FLUX.2 Klein, Z-Image, Anima, Krea-2, Qwen-Image-2.1, Ideogram 4, MiniMax H3, LTX-2 and the PiD decoders, and for the Qwen3 4B and 8B, Qwen3-VL and LTX-2 Gemma encoders.
+- **int8** (`int8_convrot`, from ComfyUI repackages): the weights stay int8 in memory on every device, including Apple Silicon, and need no setting to turn on. Supported for FLUX.1, FLUX.2 Klein, FLUX.3, Z-Image, Anima, Krea-2, Qwen-Image-2.1, Ideogram 4, MiniMax H3, LTX-2 and the PiD decoders, and for the Qwen3 4B and 8B, Qwen3-VL and LTX-2 Gemma encoders.
 - **int4** (`convrot_w4a4` or `int4_tensorwise`, ComfyUI repackages that usually keep some layers int8): the weights stay packed in memory at half a byte each and are unpacked per layer, on every device. This saves memory, not time: InvokeAI unpacks the weights for every step rather than running 4-bit matrix kernels, and 4-bit weights keep less detail than int8. Supported for the Krea-2 transformer.
-- **nvfp4** (4-bit, in ComfyUI's checkpoint format, such as Comfy-Org's builds; other nvfp4 exports such as AWQ are refused): the weights stay packed in memory and are unpacked per layer, so no special GPU is needed. Supported for the Z-Image, Krea-2, Qwen-Image and LTX-2 transformers and for the Qwen3, Qwen3-VL 4B/8B, Qwen2.5-VL and FLUX.2 Mistral encoders; the Ideogram 4 and Qwen-Image-2.1 nvfp4 transformer files are refused at install.
+- **nvfp4** (4-bit, in ComfyUI's checkpoint format, such as Comfy-Org's builds; other nvfp4 exports such as AWQ are refused): the weights stay packed in memory and are unpacked per layer, so no special GPU is needed. Supported for the FLUX.3, Z-Image, Krea-2, Qwen-Image and LTX-2 transformers and for the Qwen3, Qwen3-VL 4B/8B, Qwen2.5-VL and FLUX.2 Mistral encoders; for FLUX.3 also Black Forest Labs' own nvfp4 build, in NVIDIA ModelOpt's layout. The Ideogram 4 and Qwen-Image-2.1 nvfp4 transformer files are refused at install.
 - **fp8** (plain or `fp8_scaled`): InvokeAI keeps the weights in fp8 when [FP8 Storage](/configuration/optimization/fp8-storage/) is on, which installation does for you, or when `fp8_compute` is enabled.
 - **MXFP8** (fp8 with one scale per block of 32 weights): loaded by unpacking to BF16. Turn FP8 Storage off for these; see the [FP8 Storage caution](/configuration/optimization/fp8-storage/).
 

docs/src/content/docs/Users Guide/03.Models/03.model-format-support.mdx

@@ -1,7 +1,7 @@
 ---
 title: Model Format Support
 description: Which file formats and quantizations InvokeAI loads for every model family, text encoder, VAE and adapter.
-lastUpdated: 2026-10-31
+lastUpdated: 2026-11-06
 sidebar:
   order: 3
 ---
@@ -32,7 +32,7 @@ Others are recognized by their layer names and fail, or misbehave, only when the
 | [SD 3](/users-guide/models/local-models/sd-3/) | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
 | [FLUX.1](/users-guide/models/local-models/flux-1/) | ✓ | ✓ | ✓ | ✓ | L | ✗ | ✓ | ✓ | ✓ | ✓ |
 | [FLUX.2](/users-guide/models/local-models/flux-2/) | ✓ | ✓ | ✓ | ✓ | L | ✗ | ✓ | ✓ | ✓ | inside the Diffusers folder (FLUX.2 [dev]) |
-| [FLUX.3](/users-guide/models/local-models/flux-3/) | ✓ | ✓ | R | R | R | R | – | ✓ | – | – |
+| [FLUX.3](/users-guide/models/local-models/flux-3/) | ✓ | ✓ | ✓ | ✓ | R | ✓ | – | ✓ | – | – |
 | [CogView4](/users-guide/models/local-models/cogview4/) | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
 | [Z-Image](/users-guide/models/local-models/z-image/) | ✓ | ✓ | ✓ | ✓ | L | ✓ | ✓ | ✓ | ✓ | ✗ |
 | [Qwen-Image](/users-guide/models/local-models/qwen-image/) | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ |
@@ -49,11 +49,12 @@ Others are recognized by their layer names and fail, or misbehave, only when the
 - **int8** means ComfyUI's `int8_convrot` (`int8_tensorwise`) builds; on NVIDIA GPUs, [int8 Compute](/configuration/optimization/int8-compute/)
   runs them on the int8 tensor cores. **int4** means their packed 4-bit counterparts, `convrot_w4a4` and
   `int4_tensorwise`, which most builds mix with int8 layers. **nvfp4** and **fp8 scaled** mean ComfyUI's checkpoint
-  layouts; other exports of the same schemes (AWQ, ModelOpt) fail when the model loads. For Qwen-Image-2.1, torchao
-  exports such as unsloth's FP8 build are refused at install. MOSS-Image loads Comfy-Org's int8 build and GGUFs;
-  its fp8, nvfp4 and w4a8 transformers, and unsloth's torchao builds, are refused at install, unscaled fp8
-  included. ComfyUI's other low-bit layouts (`w4a8`, `w6a8`, SVDQuant) are not supported;
-  Krea-2 refuses them at install.
+  layouts; other exports of the same schemes (AWQ, ModelOpt) fail when the model loads. FLUX.3 also loads Black Forest
+  Labs' own builds: the nvfp4 export in NVIDIA ModelOpt's layout and `fp8r` (fp8 with one scale per row). It refuses
+  AWQ and other producers' nvfp4 at install. For Qwen-Image-2.1 and FLUX.3, torchao exports such as unsloth's FP8
+  builds are refused at install. MOSS-Image loads Comfy-Org's int8 build and GGUFs; its fp8, nvfp4 and w4a8
+  transformers, and unsloth's torchao builds, are refused at install, unscaled fp8 included. ComfyUI's other low-bit
+  layouts (`w4a8`, `w6a8`, SVDQuant) are not supported; Krea-2 refuses them at install.
 - **GGUF** covers the llama.cpp types (Q4_0 through Q8_0, the K-quants, BF16). ComfyUI-GGUF's `Q8_CR` (int8) and
   `Q4_CR` (int4) files load for Krea-2 only; for every other model with GGUF support the install fails, as it does
   for `Q4_CR` files of ComfyUI-GGUF's retired W4A16 kind.

docs/src/content/docs/Users Guide/03.Models/Local Models/flux-3.mdx

@@ -1,6 +1,6 @@
 ---
 title: FLUX.3
-description: Generate and edit images with FLUX.3 Image Klein (step-distilled) and Klein Base, including editing with up to ten reference images, LoRAs, layout boxes from Canvas regional guidance and the GGUF / single-file workflow.
+description: Generate and edit images with FLUX.3 Image Klein (step-distilled) and Klein Base, including editing with up to ten reference images, LoRAs, layout boxes from Canvas regional guidance and the GGUF, single-file and quantized builds.
 lastUpdated: 2026-11-03
 sidebar:
   order: 6
@@ -33,15 +33,46 @@ commercially.
 | Transformer build           | Transformer size | Notes                                   |
 | --------------------------- | ---------------- | --------------------------------------- |
 | bf16 (Diffusers or single file) | ≈ 10.3 GiB   | reference quality                       |
+| int8 (starter model)        | ≈ 5.4 GiB        | stays int8 on every GPU                 |
+| fp8r (Black Forest Labs)    | ≈ 5.8 GiB        | with FP8 Storage (switched on at install) or `fp8_compute`; ≈ 10.3 GiB otherwise |
+| nvfp4 (starter model, or Black Forest Labs) | ≈ 4.9 GiB | 4-bit weights, decoded on every step |
 | GGUF Q8_0 (starter model)   | ≈ 5.6 GiB        | close to bf16                           |
 | GGUF Q4_K_M (starter model) | ≈ 3.1 GiB        | lowest VRAM; fine detail differs from bf16 |
 
 The Qwen3-VL 4B encoder (≈ 8.5 GB as bf16, about half as fp8) and the FLUX.2 VAE come on top. The encoder runs
 before the transformer, so the two do not have to fit on the GPU at the same time.
 
-Reference images add to the work per step: each 1 MP reference costs about as much as the image itself. On an
-RTX 4090 a 1024² image takes about 15 s with Klein, 25 s with one reference, 50 s with three references, and
-about 50 s with Klein Base.
+Reference images add to the work per step. Measured on an RTX 4090 with the models already loaded, a whole 1024²
+image (text encoder, denoise and decode) with Klein bf16 at its defaults takes 6.5 s without a reference, 13.5 s with
+one 1 MP reference and 31.7 s with three. Klein Base at 50 steps and CFG 3.5 takes 36.7 s.
+
+### Speed and quality by build
+
+Measured on the same RTX 4090 (24 GB) with Klein at its defaults (16 steps, CFG 1.0) and 1024², three prompts with
+three seeds each:
+
+| Build | Denoise per image | With int8 Compute / `fp8_compute` | VRAM peak | PSNR against bf16 |
+| --- | --- | --- | --- | --- |
+| bf16 | 6.22 s | 6.20 s | 19.5 GiB | reference |
+| int8 | 7.01 s | 4.07 s | 14.4 GiB | 33.2 dB; 34.5 dB with int8 Compute |
+| GGUF Q8_0 | 6.78 s | not affected | 14.5 GiB | 34.4 dB |
+| fp8r (FP8 Storage on, as installed) | 6.61 s | 5.35 s | 15.0 GiB | 26.8 dB; 25.4 dB with `fp8_compute` |
+| nvfp4 (Comfy-Org or Black Forest Labs: identical images) | 6.82–6.84 s | not affected | 14.1–14.3 GiB | 22.8 dB |
+
+The VRAM peak is what `nvidia-smi` reports, text encoder and desktop included. The PSNR is the mean over the nine
+images. With `fp8_compute` on, the text encoder used here (a scaled-fp8 checkpoint) computes in fp8 too, so the PSNR
+values with the switches on compare against bf16 images made with that same encoder.
+
+- **Closest to bf16** are int8 and GGUF Q8_0, then fp8r, then nvfp4. For the prompt with a sign, every build spelled its
+  text correctly in all three seeds, with and without the compute switches. Without the switches, every quantized build
+  scores its lowest per-image PSNR on the same seed of the sign prompt, whose letter colors shift in all of them, Q8_0
+  included.
+- **Speed:** without a compute switch, every quantized layer is dequantized on each forward, so on this card the
+  quantized builds take up to 13 % longer than bf16. [int8 Compute](/configuration/optimization/int8-compute/) makes
+  the int8 build the fastest, 1.52× as fast as bf16, and
+  [`fp8_compute`](/configuration/optimization/fp8-storage/#fp8-compute) makes fp8r 1.16× as fast as bf16. Neither
+  affects nvfp4 or GGUF.
+- **Memory:** the quantized builds peak about 5 GiB below bf16.
 
 ## Installing
 
@@ -65,10 +96,33 @@ FLUX.3 needs three components:
 When you select a GGUF or single-file FLUX.3 model, pick the VAE and the Qwen3-VL encoder under **Components** if
 they are not filled in. A Diffusers model uses its bundled components unless you override them there.
 
-:::note[Quantized single files]
-The fp8, int8 and nvfp4 transformer single files from Black Forest Labs and Comfy-Org are not supported yet. Installing
-one is refused with a message saying so. Use the bf16 file or a GGUF.
-:::
+### Quantized single files
+
+Comfy-Org's int8 and nvfp4 builds of both checkpoints are starter models. Black Forest Labs publishes an fp8 build
+(`fp8r`) and an nvfp4 build of each as well, in the `variants/` folder of its repositories. They are not starter models,
+because Klein's and Klein Base's files are both called `model.safetensors`. Install one by URL in the Model Manager,
+then rename it so the models can be told apart. The URLs are pinned to the revisions InvokeAI was checked against:
+the Klein file was loaded in full, the Klein Base file compared with it by its header.
+
+- Klein: `https://huggingface.co/black-forest-labs/flux-3-image-klein/resolve/337337621b8526e120f2275d250242f4a6bedd75/variants/fp8r/model.safetensors`
+- Klein Base: `https://huggingface.co/black-forest-labs/flux-3-image-klein-base/resolve/3f7fa5ee22ca1d5a5cc095ac7cc96e6a173b4c86/variants/fp8r/model.safetensors`
+
+Like every Black Forest Labs repository, these need your HuggingFace token. For nvfp4, prefer the Comfy-Org starter
+model to `variants/nvfp4/`: InvokeAI turns Black Forest Labs' file into exactly Comfy-Org's bytes while loading it, an
+extra pass over the weights on every load.
+
+- **int8** keeps its quantized layers in int8 on every GPU and decodes them on every step. On an RTX 30-series or
+  newer, [int8 Compute](/configuration/optimization/int8-compute/) multiplies them in int8 instead.
+- **nvfp4** keeps 33 of the 43 transformer blocks in 4 bits and decodes them on every step, on every GPU.
+- **fp8r** stores fp8 weights with one scale per row. With [FP8 Storage](/configuration/optimization/fp8-storage/), which
+  installing it switches on, or with `fp8_compute`, the weights stay fp8; otherwise they are expanded to bf16 as the
+  model loads.
+
+FP8 Storage does not apply to the int8 and nvfp4 builds: their quantized layers are smaller already, and the layers
+they keep in bf16 stay bf16. The Model Manager can still show the toggle as on for an nvfp4 build, because installing
+switches it on for any file holding fp8 numbers, and nvfp4's block scales are fp8. It has no effect there. Other
+quantized files, such as AWQ or bitsandbytes exports or nvfp4 files from other tools, are refused at install with a
+message saying why.
 
 ## Reference images
 

docs/src/content/docs/configuration/Optimization/fp8-storage.mdx

@@ -11,7 +11,7 @@ FP8 Storage cuts a model's VRAM footprint roughly in half by keeping weights on
 It pairs well with [Low-VRAM mode](/configuration/optimization/low-vram-mode/): low-VRAM mode streams layers between RAM and VRAM, while FP8 Storage shrinks the layers themselves.
 
 :::caution[For full precision models only]
-FP8 Storage is meant for **full precision** checkpoints (FP16 / BF16 / FP32). It does nothing for **GGUF**, **NF4** and [**SDNQ**](/configuration/optimization/sdnq-quantization/) checkpoints, which carry their own storage precision, so the Model Manager does not show the toggle for them (see [Where the toggle is shown](#where-the-toggle-is-shown)). **int8** and **nvfp4** single-file checkpoints keep their quantized layers as they are — the loader returns a module type the FP8 layer cast does not touch — so there the toggle reaches only the layers the build ships in full precision, and on an **Ideogram 4** or **Qwen-Image-2.1** int8 file nothing at all. On single-file checkpoints that ship *scaled* fp8 layers, the toggle keeps those layers in FP8 with their own scale instead of unpacking them; that is what FLUX.1, FLUX.2, Z-Image, Anima, Krea-2, Qwen-Image, Qwen-Image-2.1 and Ideogram 4 all do. **MXFP8 is the exception, and there the toggle costs quality:** those files carry one exponent per 32-element block, which no GPU before Blackwell can apply, so the layers are unpacked at load and the toggle then re-encodes them as fp8 *without* any scale. Blocks whose scale sits far below 1 lose their weights to underflow. Leave it off for an MXFP8 checkpoint — and because installing switches it on for every checkpoint with FP8 weights, MXFP8 included, turn it off under **Default Settings** after installing one. If your model is already quantized, use its full-precision variant to get the full effect of FP8 Storage. Checkpoints that store FP8 weights are the exception: InvokeAI loads them at BF16 unless FP8 Storage is on, so they get it automatically when installed (see [When installing](#when-installing)).
+FP8 Storage is meant for **full precision** checkpoints (FP16 / BF16 / FP32). It does nothing for **GGUF**, **NF4** and [**SDNQ**](/configuration/optimization/sdnq-quantization/) checkpoints, which carry their own storage precision, so the Model Manager does not show the toggle for them (see [Where the toggle is shown](#where-the-toggle-is-shown)). **int8** and **nvfp4** single-file checkpoints keep their quantized layers as they are — the loader returns a module type the FP8 layer cast does not touch — so there the toggle reaches only the layers the build ships in full precision, and on an **Ideogram 4** or **Qwen-Image-2.1** int8 file, or a **FLUX.3** int8 or nvfp4 file, nothing at all. On single-file checkpoints that ship *scaled* fp8 layers, the toggle keeps those layers in FP8 with their own scale instead of unpacking them; that is what FLUX.1, FLUX.2, FLUX.3 (Black Forest Labs' `fp8r` build), Z-Image, Anima, Krea-2, Qwen-Image, Qwen-Image-2.1 and Ideogram 4 all do. **MXFP8 is the exception, and there the toggle costs quality:** those files carry one exponent per 32-element block, which no GPU before Blackwell can apply, so the layers are unpacked at load and the toggle then re-encodes them as fp8 *without* any scale. Blocks whose scale sits far below 1 lose their weights to underflow. Leave it off for an MXFP8 checkpoint — and because installing switches it on for every checkpoint with FP8 weights, MXFP8 included, turn it off under **Default Settings** after installing one. If your model is already quantized, use its full-precision variant to get the full effect of FP8 Storage. Checkpoints that store FP8 weights are the exception: InvokeAI loads them at BF16 unless FP8 Storage is on, so they get it automatically when installed (see [When installing](#when-installing)).
 :::
 
 ## Requirements
@@ -76,6 +76,7 @@ FP8 Storage is **only** applied to layers where the precision trade-off is accep
 | --- | --- |
 | Main models: SD1, SD2, SDXL, SDXL Refiner, SD3, CogView4 | Yes |
 | FLUX.1, FLUX.2 (all variants) | Yes |
+| FLUX.3 | Yes — except int8 and nvfp4 single files, where it does nothing. The toggle can still show as on for an nvfp4 build, since installing switches it on for its fp8 block scales |
 | Z-Image, Anima, Krea-2, Qwen-Image, Qwen-Image-2.1, ERNIE-Image, MOSS-Image | Yes |
 | Ideogram 4 (single-file safetensors) | Yes — both transformer branches |
 | LTX-2 | Yes |
@@ -147,7 +148,7 @@ It is for models that were **already saved in FP8** by whoever published them 
 
 For these, FP8 Storage does not re-encode anything — it simply stops InvokeAI from unpacking them. That matters because the file stores a per-tensor scale alongside each weight, and re-encoding the unpacked result would throw that scale away: on FLUX.2 Klein 4B roughly 3% of the weights would round to zero, for a file that was already one byte per weight. What it costs instead is a little speed, since each layer is unpacked on use. Measured on a 4090 with `fp8_compute` off, the Ideogram 4 fp8 pair generates 1024px in 40.6 s against 35.6 s on the FP8 tensor cores, and holds 8.7 GB per branch instead of the 17.3 GB the unpacked weights need — which is the difference between fitting on a 24 GB card and running out of memory during the first step.
 
-The loader reports what it kept, naming the setting that kept it — for example `Ideogram 4: kept 208 layer(s) in fp8 (scaled fp8 checkpoint, kept for FP8 Storage, dequantized per forward)`. Some loaders then hand the model to the layer cast anyway, which declines it and logs `FP8 storage skipped ... already fp8`; on FLUX.1, FLUX.2, Z-Image and Anima you therefore see both lines for the same model. Both are the intended outcome, not a failure.
+The loader reports what it kept, naming the setting that kept it — for example `Ideogram 4: kept 208 layer(s) in fp8 (scaled fp8 checkpoint, kept for FP8 Storage, dequantized per forward)`. Some loaders then hand the model to the layer cast anyway, which declines it and logs `FP8 storage skipped ... already fp8`; on FLUX.1, FLUX.2, FLUX.3, Z-Image and Anima you therefore see both lines for the same model. Both are the intended outcome, not a failure.
 
 Not every part of a model stays in FP8 — the small, precision-sensitive pieces are always unpacked. Those are a tiny share of the weights, so you still get nearly the full VRAM saving.