FLUX.3 Klein: Run the Latest Open-Source FLUX Locally
FLUX.3 is the latest generation of image models from Black Forest Labs. The split within this generation in ComfyUI is clear: the cloud-hosted version is only available as a pay-per-image API Partner Node, while the locally runnable open-source release is klein (officially written FLUX.3 [klein])—download the weights once, run them on your own GPU, with no API key and no per-image credits.
klein packs text-to-image and instruction-based editing into the same set of weights: generation uses prompts, while editing uses "instructions + reference images," with multiple reference images referenced via tags like <ref_image_0> and <ref_image_1>. ComfyUI has supported it natively since v0.41.0, and ships four official templates. This page walks you through the FLUX.3 Klein workflow end to end, from downloading the weights to producing edited images.
What You'll Be Able to Do After This Lesson
- Load the official template and run FLUX.3 Klein text-to-image: images generated with the default 50 steps and cfg 3.5
- Do instruction-based editing with the same set of weights: change a dress color or swap earrings while the rest of the image stays as is
- Reference images with
<ref_image_0>and mark edit regions with<obj_1>to write precise editing instructions - Switch to the Distilled version: fast 16-step, guidance-free generation
- Tell apart the base / distilled and int8 / bf16 weight files so you never download the wrong one again
Your Current Struggles
- You want to try the latest FLUX.3, but the cloud-hosted version only offers a pay-per-image API, the only locally runnable option is klein, and tutorials in Chinese are hard to find
- You follow older tutorials for FLUX.1 and FLUX.2 to build the workflow: the CLIPLoader lacks the
flux3type, the reference image nodes don't match, and the canvas is covered in red - You want to change just one object in a photo (swap earrings, change a dress color), but a regular img2img run repaints the whole face
When to Use This Approach
When you need:
- The latest generation of open-source FLUX: text-to-image and instruction-based editing sharing one set of weights
- Precise one-sentence editing: change colors, swap accessories, keep the rest of the image intact
- Multi-reference-image composition: combine the best parts of multiple images into one output
- Fast low-step generation: the distilled version runs in 4–16 steps, guidance-free
And you don't want to:
- Open a pay-per-image API for the FLUX.3 hosted version
- Force multi-image tasks into the single-reference-image workflow of FLUX.1 Kontext
🎒 Prerequisites
- You've run the FLUX.2 workflow: get familiar with the FLUX family loader patterns in that lesson first
- You know how to load a workflow from the template library and run it with
Ctrl+Enter(if you forgot, review your first generation; for detailed template library usage, see the template library tutorial) - You're familiar with the model directory rules: files go into the corresponding subdirectories under
models/(review where models go) - ComfyUI is updated to 0.41.0 or later (native support for FLUX.3 Klein shipped with v0.41.0; the latest version at the time of writing is v0.44.0, see the changelog for version changes)
- A Hugging Face account: the weights are in a gated repository, so you must accept the FLUX Kommunity License before downloading
- Free up disk space for the five model files (the template defaults to the int8 quantized version; check the repository page for exact sizes)
Core Idea
First, remember the five key designs of FLUX.3 Klein; every step that follows verifies them:
- One set of weights, two tasks. Text-to-image and instruction-based image editing load the same checkpoint; for editing, the reference image is encoded into the conditioning, and the instruction describes "what to change it into."
- Dual checkpoints. The full version (base) produces images in 50 steps; the step-distilled version (Distilled) is designed for guidance-free sampling, producing images in 4–16 steps, with the template defaulting to 16 steps.
- New encoder, old VAE. The text encoder is replaced with Qwen3-VL-4B, loaded via
CLIPLoaderwith type set toflux3; the VAE directly reuses theflux2-vae.safetensorsfrom FLUX.2. - Reference image goes into conditioning. The
Set Reference Multi Latentnode encodes reference images and appends them to both the positive and negative conditioning, supporting up to 100 images, and also outputs an empty latent prepared at the reference image's dimensions to serve as the canvas. - Optional prompt upsampler. A Qwen3.5 9B small model, enabled by default in the template; it first expands your short phrase into a full description before sending it to sampling; turn off the switch if you don't want it.
Compared with the previous two generations, the biggest node-level changes are the encoder and the reference image:
| Component | FLUX.1 | FLUX.2 | FLUX.3 Klein |
|---|---|---|---|
| Text encoder loading | DualCLIPLoader | CLIPLoader (type flux2) | CLIPLoader (type flux3) |
| Text encoder | T5 + CLIP | Mistral | Qwen3-VL-4B |
| VAE | ae.safetensors | FLUX.2 VAE | Reuses FLUX.2 VAE |
| Reference image | Kontext, single image | ReferenceLatent Multiple images | Set Reference Multi Latent (up to 100 images) + <ref_image_N> prompt markers |
How to choose between the full version and the distilled version:
| base (full version) | Distilled (distilled version) | |
|---|---|---|
| Filename (int8) | flux3-image-klein-base-int8-convrot.safetensors | flux3-image-klein-int8-convrot.safetensors |
| Steps | 50 | 4–16 (template default 16) |
| cfg | Text-to-image 3.5 / image editing 1 | Fixed 1 (no adjustment exposed) |
| Negative prompt | Exposed in the template, empty by default | Not exposed; negative conditioning set directly to empty |
| Best for | Quality-first formal image generation | Speed-first daily iteration |
Follow Along
Step 1: Load the FLUX.3 Klein workflow template (update ComfyUI first)
Why: Native support for FLUX.3 Klein, along with the Set Reference Multi Latent and FLUX.3 Layout Prompt built-in nodes, are all core additions in v0.41.0; the official template also requires 0.41.0 or newer, so older versions will inevitably show red nodes when loading.
- First update ComfyUI to 0.41.0 or newer (at the time of writing, the latest is v0.44.0)
- Open the template library (Browse Templates) and search for "FLUX 3 Image Klein"; you will see four official templates:
| Template name (Chinese name in the template library) | Purpose |
|---|---|
| FLUX 3 Image Klein: Text to Image | Full-version text-to-image (the main one used in this lesson) |
| FLUX 3 Image Klein Distilled: Text to Image | Distilled-version text-to-image |
| FLUX 3 Image Klein: Image Editing | Full-version instruction-based image editing |
| FLUX 3 Image Klein Distilled: Image Editing | Distilled-version instruction-based image editing |
- First load "FLUX 3 Image Klein: Text to Image"
You should see: on the canvas, a large subgraph node named Text to Image (FLUX 3 Image Klein), followed by SaveImage and ResolutionSelector, with no red nodes anywhere.
- Template loaded, no red nodes on the canvas
💡 What is a subgraph
This template packages the loaders, sampler, and canvas size into a single subgraph node. Double-click the subgraph node to look inside: UNETLoader, two CLIPLoaders (encoder + upsampler), VAELoader, and KSampler are all in there. For everyday use, you only need to fill in parameters on the outer node.
Step 2: Accept the agreement, download the FLUX.3 Klein five-file set, and put them in place
Why: The weights are hosted in the gated Hugging Face repository black-forest-labs/flux-3-image-klein-comfy; you cannot get the files without first accepting the FLUX Kommunity License. The template uses the int8 (convrot) single-file version by default in order to keep VRAM usage down.
- Log in to Hugging Face, open the repository page above, and click to accept the agreement
- Download these five files (they are what the template loads by default):
| File | Put into | Purpose |
|---|---|---|
flux3-image-klein-base-int8-convrot.safetensors | models/diffusion_models/ | Full-size diffusion model |
flux3-image-klein-int8-convrot.safetensors | models/diffusion_models/ | Distilled diffusion model |
qwen3vl_4b_int8_convrot.safetensors | models/text_encoders/ | Text encoder (Qwen3-VL-4B) |
qwen3.5_9b_flux3_prompt_upsampler_w4a8.safetensors | models/text_encoders/ | Prompt upsampler (Qwen3.5 9B) |
flux2-vae.safetensors | models/vae/ | VAE (carried over from FLUX.2) |
📂 ComfyUI/
└── 📂 models/
├── 📂 diffusion_models/
│ ├── flux3-image-klein-base-int8-convrot.safetensors
│ └── flux3-image-klein-int8-convrot.safetensors
├── 📂 text_encoders/
│ ├── qwen3vl_4b_int8_convrot.safetensors
│ └── qwen3.5_9b_flux3_prompt_upsampler_w4a8.safetensors
└── 📂 vae/
└── flux2-vae.safetensorsYou should see: double-click into the subgraph, and the corresponding files can be selected in the dropdown lists of UNETLoader, the two CLIPLoaders, and VAELoader; if a model is missing, the template will flag it in red.
- All five files appear in the corresponding directories and can be selected in the loaders
💡 Want to save one download
If you're only running the full-size version first, the distilled file (row 2) can be downloaded later, before step 5. But the text encoder, upsampler, and VAE files are shared by all four templates, so downloading them all at once is the easiest.
Step 3: Get FLUX.3 Klein text-to-image working (image in 50 steps)
Why: first validate the whole pipeline with the official default parameters before talking about tuning—FLUX.3's defaults are the official, well-tuned balance point.
- Fill in the prompt in the subgraph node's
positive_prompt. Short phrases are fine: the prompt upsampler is on by default, and Qwen3.5 9B will first expand your short phrase into a full description before sampling. To use only your own original words, turn off theenable_prompt_upsamplerswitch ResolutionSelectorto select the aspect ratio, default 1:1 square (about 1MP); to customize the size, disconnect its wire to the subgraph and editwidth/heighton the subgraph directly- Confirm the sampling parameters are the template defaults:
steps50,cfg3.5,euler+simple - Press
Ctrl+Enterto run
You should see: the progress bar runs through all 50 steps, and the image is saved into ComfyUI/output/ by the SaveImage node. The template's built-in example prompt generates a close-up of an athlete on a white background.
- Your first FLUX.3 image appears in
output/
⚠️ When the upsampler is on, don't debug against your own original words
The upsampler rewrites and expands your prompt first, so the words you wrote and the words actually sent to sampling are not exactly the same. When troubleshooting prompt issues, first turn off enable_prompt_upsampler and then compare results.
Step 4: Get FLUX.3 Klein instruction-based editing working (change the dress color)
Why: klein's core design is using the same set of weights for editing—the reference image goes into the conditions, and the instruction only changes the target region. This is the fundamental difference between FLUX.3 editing and ordinary image-to-image.
- Load "FLUX 3 Image Klein: Image Editing" from the template library
- Replace the image in the
LoadImagenode (node 54) with your own. The template's example image is a portrait of a lady in a blue silk gown (fashion_portrait_blue_silk_gown_vis.png) - Look at the prompt chain: the
FLUX.3 Layout Promptnode containsIn <ref_image_0>, change the dress color <obj_1> to red—<ref_image_0>refers to reference image 1 attached toSet Reference Multi Latent, and<obj_1>refers to box 1 drawn inCreate Bounding Boxes(in the template it covers the dress, described as dress) - This instruction goes through the Qwen3.5 9B upsampler for expansion by default—in the editing templates, the upsamplercan also see the reference image, so the expanded description fits the picture better
KSamplerparameters: 50 steps,cfg1,euler+simple. Note that the editing cfg is 1, not the text-to-image value of 3.5- Run, and drag the slider in the
ImageComparenode to compare before and after
You should see: only the dress turns red, while the face, pose, background, and composition all stay the same.
- Before-and-after comparison via
ImageCompare: the target region changed, everything else stays the same
💡 Why the output size follows the reference image
Set Reference Multi Latent scales each reference image to about 1MP before encoding, and outputs an empty latent prepared at that size for the sampler to use as a canvas. To customize the output size, connect the LATENT of the template's unwired Empty Flux 2 Latent node (default 1024×1024) to the latent_image of KSampler.
Step 5: Switch to the Distilled version for fast image generation in 16 steps
Why: the distilled version is designed for guidance-free sampling and produces images in 16 steps, making daily iteration much faster than the full-size version's 50 steps. It's the right way to "quickly lay a base → refine with the full-size version once satisfied".
- Load the "FLUX 3 Image Klein Distilled: Text-to-Image" template (or simply swap
UNETLoadertoflux3-image-klein-int8-convrot.safetensorsin the full-size version—the distilled file is the one withoutbasein its filename) - Keep
stepsat 16; it can be adjusted within 4–16 - Ignore cfg: the distilled version is fixed at 1, the template doesn't even expose this parameter, and raising it won't improve anything
- Run. The distilled template's example prompt is a full description of a retro hotel neon night scene, and the upsampler is likewise on by default
You should see: the image completes in 16 steps, with a noticeably shorter wait than the full-size version's 50 steps.
- Distilled version successfully generates an image in 16 steps
The distilled editing template ("FLUX 3 Image Klein Distilled: Image Editing") has only one text prompt, and the negative condition is emptied directly with ConditioningZeroOut. Its example swaps a person's earrings, and the prompt is worth copying to learn the writing style:
In <ref_image_0>, replace the earring <obj_1> with a single large openwork
metal statement earring, one bold curved pendant, intricate hollow metal
cutouts, layered metal wires, polished warm bronze finish, structured
artistic shape, keep it attached to the correct ear position. Match the
character's existing lighting, shadows and skin tone. No pearls, no pearl
beads, no scattered small beads. Keep all other parts of the image
completely unchanged.The new earrings' shape, material, and color are all spelled out, along with "what not to include" (No pearls…) and "what to keep" (Keep all other parts…)—this is the officially demonstrated FLUX.3 editing prompt structure.
Checkpoint ✅
- Text-to-image template works: 50 steps, cfg 3.5, image appears in
ComfyUI/output/ - Editing template works: only the target region is modified, with a clear before-and-after comparison in
ImageCompare - Can explain the encoder change: FLUX.3 uses
CLIPLoaderwith type set toflux3, loading the Qwen3-VL-4B encoder - The distilled version generates images in 16 steps successfully, and you know that raising cfg is meaningless
- All five model files are in the correct directories and selectable from the loader dropdown
Pitfall reminders
❌ Raising cfg on the distilled version hoping to improve quality
The distilled version is designed for guidance-free sampling, with cfg fixed at 1; the template doesn't even expose the parameter.
Correct approach: for better results, raise steps within 4–16 and write more detailed prompts; if VRAM exceeds 24GB, switch to bf16 weights (see Advanced Tips).
❌ Editing prompt only says "replace the earrings"
FLUX.3 editing expects a full description of the result: what the new object looks like (shape, material, color), what should not appear, and what stays unchanged. If you only describe the action and not the result, the model has to imagine the new earrings itself.
Correct approach: follow the structure of the official examples — describe the new object + match the ambient lighting + exclusions + things to keep (see the example prompt in step 5).
❌ Downloading the wrong checkpoint: the base and distilled filenames differ by only one word
flux3-image-klein-**base**-int8-convrot.safetensors is the full version, and flux3-image-klein-int8-convrot.safetensors is the distilled version. Downloading the wrong one causes odd issues like "step counts don't match" or "the distilled version wastes time running 50 steps".
Correct approach: look for base in the filename; download both and switch depending on the scenario.
❌ ComfyUI version too old, the template is a sea of red
Set Reference Multi Latent and FLUX.3 Layout Prompt are both built-in nodes newly added in v0.41.0; they simply don't exist in older versions. This is not a missing custom node — installing node packages won't fix it.
Correct approach: update the ComfyUI core to 0.41.0 or later (distributed with stable releases starting from 0.41.1), then reload the template.
Advanced Tips (Optional)
Compositing multiple reference images
The image slots of Set Reference Multi Latent can keep growing (the node supports 1–100 images), with each image corresponding in slot order to <ref_image_0>, <ref_image_1>, etc. in the prompt. The official recommendation, as with the reference pipeline, is to write every reference image into both the positive and negative prompts. When multiple Set Reference Multi Latent nodes are chained, reference images accumulate rather than get replaced.
Bounding-box region editing
Use the Create Bounding Boxes node to draw boxes on the image and write a one-sentence description for each box (colors must go into the description; the palette doesn't take effect), then FLUX.3 Layout Prompt assembles the box numbers, coordinates, and descriptions into a layout table that FLUX.3 can read and appends it to the prompt, referencing them with <obj_1>, <obj_2>. In the text-to-image template, the output of FLUX.3 Layout Prompt is by default only connected to PreviewAny for preview and not wired into the subgraph — to use it, connect its STRING output to the prompt input of the subgraph node.
Reference image resolution is a cost knob
Set Reference Multi Latent by default resize to 1MP (about 1024×1024). The megapixels parameter can be adjusted between 0.01–16.0: raising it preserves more reference image detail at the cost of VRAM and time. Black Forest Labs' own pipeline keeps the reference image's native resolution, up to about 16MP.
VRAM over 24GB: switch to bf16
Swap the diffusion model for the bf16 version of the same checkpoint (full version flux3-image-klein-base-bf16.safetensors, distilled version flux3-image-klein-bf16.safetensors), and also swap the prompt upsampler for the bf16 version from the repository. Official note: bf16 reproduces long prompts more accurately.
If you want the hosted FLUX.3 version
Only klein is available locally as open source. The hosted version goes through ComfyUI's FLUX 3 Image Partner Node (billed per image via API), suitable for scenarios where you don't want to download weights and just want to generate images directly.
Lesson Summary
✅ In this lesson you got the FLUX.3 Klein workflow working in two modes:
- ✅ Text to image: official template + the five-weight set, 50 steps, cfg 3.5 for image generation
- ✅ Instruction-based editing:
<ref_image_0>to reference images,<obj_1>to mark regions, 50 steps, cfg 1, changing only the target - ✅ Distilled version: 16 steps, cfg 1 guidance-free, for fast iteration
- ✅ You can now identify all five weight files and the difference between base / distilled
Key configuration fields recap:
| Field | Recommended value | Notes |
|---|---|---|
CLIPLoader type | flux3 | Specific to FLUX.3, loads the Qwen3-VL-4B encoder |
UNETLoader | flux3-image-klein-base-int8-convrot.safetensors | Full version; the distilled filename doesn't contain base |
steps | 50 (base) / 16 (distilled) | The distilled version can be adjusted between 4–16 |
cfg | 3.5 (base text-to-image) / 1 (others) | Fixed at 1 for the distilled version; raising it has no effect |
| sampler / scheduler | euler / simple | Consistent across the four official templates |
Set Reference Multi Latent | resize / 1 MP | Reference image scaling; the output latent follows this size |
enable_prompt_upsampler | On (default) | Qwen3.5 9B expands short prompts; turn it off when debugging |
Next Lesson Preview
That wraps up image models; the next lesson moves to video: Wan2.2 5B: running text-to-video and image-to-video on 8GB of VRAM. You will learn:
- Running text-to-video with the 5B TI2V single model on 8GB of VRAM
- An image-to-video workflow that brings static photos to life
- Wan2.2's low-VRAM optimization approach
Appendix: Source Code Reference
— click to expand and view source code locations
Updated: 2026-11-05 (ComfyUI v0.44.0 / Template Library v0.11+)
The parameters on this page were all verified against the actual node values in the four template JSON files above (KSampler steps / cfg, loader filenames, the resize / 1MP of Set Reference Multi Latent) and the official tutorial.