ComfyUI-Nunchaku-Klein Introduction
ComfyUI-Nunchaku-Klein workflow screenshot
ComfyUI-Nunchaku-Klein adds custom nodes for using Nunchaku FLUX.2 Klein in ComfyUI. It supports image generation from text, editing with one or more reference images, LoRAs, and controls intended to help you manage details, color, and the influence of references.
The extension is independent of the official ComfyUI-Nunchaku project. Some of its enhancer nodes were adapted from ideas in ComfyUI-Flux2Klein-Enhancer, but they do not behave exactly like the original nodes.
The most important distinction is between standard features, which work with the community-maintained Vitoom Nunchaku backend, and Direct K/V features, which require the author's extended Vitoom Nunchaku backend. Check which kind of node you are using before troubleshooting a workflow.
How ComfyUI-Nunchaku-Klein Works
Think of a ComfyUI workflow as a set of connected workstations. One part loads a Klein model, another supplies your prompt or reference images, and other nodes adjust how those inputs influence the result. ComfyUI then passes the information through the connected nodes to generate or edit an image.
- Text-to-image begins with a written description. The model uses that description to produce an image.
- Reference editing adds an image for the model to work from. With multiple references, you can bring several visual sources into one workflow.
- Enhancer and controller nodes give you additional ways to shape aspects of the result, such as detail, color, or the balance between your text and references. Their effect depends on the model, the workflow, and the settings you choose.
- LoRAs are optional model adjustments. You can attach one or several to a model branch and control their strengths without changing the base model.
Some reference controls use Direct K/V, a backend-assisted way to influence how the model uses reference information. These nodes need capabilities that the ordinary Vitoom Nunchaku backend does not provide. A workflow using them will therefore need the extended backend even if a simpler workflow works normally.
Results may vary between runs. The author observed materially different Nunchaku FLUX.2 Klein outputs from repeated executions with identical workflow inputs and seed. This also occurred in plain text-to-image workflows, so it should not be attributed solely to references, LoRAs, or reference-weight nodes.
ComfyUI-Nunchaku-Klein Features
Reference and image controls
The extension supports ordinary single- and multi-reference editing for both 4B and 9B. Multi Reference Latent helps you work with more than one reference. Mask Ref Controller and Color Anchor provide additional reference-related controls. Sectioned Encoder, Detail Controller, and Klein Enhancer offer further ways to shape the image. These enhancer nodes work with both 4B and 9B on the Vitoom Nunchaku backend.
For example, you might begin with a basic reference-edit workflow, then add a color or detail control when the result needs more direction. Change one setting at a time and compare outputs: that makes it easier to tell which control helped. The source documentation does not define exact ranges or guaranteed visual effects for these controls, so treat their names as a guide rather than a promise of a particular result.
The extension also includes Differential Diffusion, though the author notes that FLUX.2 Klein does not work particularly well with it by default.
Text and reference balance
On 9B, the standard Vitoom Nunchaku backend supports Klein Text Enhancer, Ref Latent Weight (Compatibility version), Text/Ref Balance (Compatibility version), and Identity Guidance. These give you options for workflows where prompt wording and reference influence both matter. The compatibility versions are distinct from the Direct K/V versions.
An earlier Text/Ref Balance implementation was described as experimental; the author suggested a balance value of 0.50–1.00 for that implementation. This is not a documented universal range for every balance node. Check which node your workflow uses.
For 4B and 9B, the extended backend enables Ref Latent Weight (Direct K/V), Text/Ref Balance (Direct K/V), Ref Latent Controller (Direct K/V), and Identity Feature Transfer Final. Identity Feature Transfer Final requires the newer backend APIv3. It does not support zero_unmasked_tokens or sigma-aware strength scheduling.
LoRA loading
Both 4B and 9B have LoRA support. A LoRA lets you apply an additional model adjustment to a workflow. The Nunchaku FLUX.2 Klein Power LoRA Loader makes it easier to manage several LoRAs on one model branch:
- Add LoRAs from a searchable picker. Searches are case-insensitive and match text anywhere in a LoRA’s full path.
- Set each LoRA’s strength, including signed values, or use
0to make a row contribute nothing. - Enable, disable, remove, and reorder rows. Order matters because the loader publishes an ordered LoRA specification.
- Keep LoRAs already inherited by the model branch.
Selecting + Add LoRA creates an enabled row at strength 1.0 after you choose a LoRA. Closing the picker with Escape or clicking outside it adds nothing. The Power Loader provides a more convenient interface over the ordinary LoRA-loader behavior; it is not a separate image-generation method. Its row editor is designed for ComfyUI’s Nodes 2.0 frontend and does not require rgthree.
ComfyUI-Nunchaku-Klein Models
The extension documents support for two FLUX.2 Klein model profiles:
| Profile | When to use it | Documented support |
|---|---|---|
| 9B | Use for workflows that need the 9B-only standard enhancer and compatibility nodes. | Basic generation, LoRAs, reference editing, shared enhancer nodes, plus Klein Text Enhancer, compatibility Ref Latent Weight, compatibility Text/Ref Balance, and Identity Guidance. |
| 4B | Use for workflows built around the 4B profile and its Qwen3 4B text conditioning. | Basic text-to-image generation, LoRAs, ordinary single- and multi-reference editing, and the shared enhancer nodes. |
The 4B profile is strict: use workflows and conditioning intended for 4B rather than assuming a 9B setup will transfer unchanged. The supplied documentation does not establish a reliable speed, memory, or image-quality comparison between 4B and 9B, so choose according to the nodes your workflow requires and test the results you prefer.
Direct K/V controls and Identity Feature Transfer Final are documented for both profiles when the extended backend is available. The standard 9B-only compatibility controls should not be mistaken for those extended-backend features.
What’s New with ComfyUI-Nunchaku-Klein
The entries below follow the author’s release notes, with the newest changes first.
| Date and version | Change | Why it matters to you |
|---|---|---|
| August 20, 2026 — v1.2.1 | Fixed some LoRA incompatibilities. | Improves compatibility for affected LoRA workflows. |
| August 20, 2026 — v1.2.0 | Added the Power LoRA Loader for Nodes 2.0. | Lets you search, organize, enable, and adjust multiple LoRAs in one node. |
| August 19, 2026 — v1.1.0 | Added the 4B Direct K/V callback family and 4B Identity Feature Transfer Final. | Extends advanced reference and identity workflows to 4B with the required backend. |
| August 19, 2026 — v1.0.1 | Added 4B Multi Reference Latent, Mask Ref Controller, Color Anchor, Klein Enhancer, Sectioned Encoder, and Detail Controller. | Gives 4B workflows more of the reference and enhancer controls already available elsewhere in the extension. |
| August 19, 2026 — v1.0.0 | Added ordinary single- and multi-reference editing for 4B. | Allows 4B workflows to edit from one or several references. |
| August 14, 2026 | Added profiled 4B text-to-image generation with native Qwen3 4B conditioning and profile-aware 4B LoRA support. | Makes basic 4B generation and LoRA use available. |
| August 12, 2026 — v0.9.0 | Added Identity Feature Transfer Final, requiring the newer Nunchaku backend APIv3. | Adds an identity-oriented option, subject to its documented unsupported settings. |
| August 11, 2026 — v0.8.0 | Added Text/Ref Balance (Direct K/V). | Provides another way to control text and reference influence with the modified backend. |
| August 11, 2026 — v0.7.0 | Added Ref Latent Weight (Direct K/V). | Introduced a reference-weight control that requires the extended backend. |
| August 9, 2026 — v0.6.0 | Added experimental Text/Ref Balance. | Introduced a balance control; the author suggested 0.50–1.00 for its balance setting. |
| August 9, 2026 — v0.5.0 | Added Ref Latent Weight. | Introduced a way to adjust reference-latent influence. |
| August 8, 2026 — v0.4.1 | Added Multi Reference Latent, Mask Ref Controller, and Color Anchor. | Expanded reference-based editing options. |
| August 6, 2026 — v0.3.0 | Added Sectioned Encoder and Detail Controller. | Added more image-shaping controls. |
| August 5, 2026 — v0.2.0 | Added Klein Enhancer. | Introduced the extension’s enhancer functionality. |
| August 4, 2026 | Established most basic 9B functionality, LoRAs, multi-reference editing, and an experimental Klein Text Enhancer. | Formed the initial set of usable 9B workflows. 4B was not supported in this release. |
Troubleshooting ComfyUI-Nunchaku-Klein
A Direct K/V or Identity Feature Transfer node does not work
- Check whether the node name includes Direct K/V, or whether you are using Identity Feature Transfer Final.
- Confirm that your workflow uses the author's extended Vitoom Nunchaku backend. Ordinary Vitoom Nunchaku is sufficient for the documented standard features, but not these nodes.
- For Identity Feature Transfer Final, confirm that the backend provides the required APIv3.
- Do not rely on
zero_unmasked_tokensor sigma-aware strength scheduling with Identity Feature Transfer Final; those options are not supported.
A 4B workflow cannot use a node shown in a 9B workflow
- Check the node’s profile in the features and models sections.
- If it is listed as 9B only, choose a supported 4B control instead of assuming the two profiles have identical nodes.
- For 4B text-to-image workflows, use the documented native Qwen3 4B conditioning path.
A LoRA does not appear or behaves unexpectedly
- In the Power LoRA Loader, search for part of the LoRA’s name or full path; the picker matches substrings without regard to capitalization.
- Confirm that you selected the LoRA. Opening + Add LoRA and then dismissing the picker does not create a row.
- Check that the row is enabled and its strength is not
0. - Review the order of multiple rows and any LoRAs inherited by the model branch.
- If you are using an earlier extension release and encounter a compatibility problem, note that v1.2.1 included fixes for some LoRA incompatibilities.
The same seed produces different images
The author observed different outputs across repeated Nunchaku FLUX.2 Klein runs with identical inputs and seed, including workflows without references or LoRAs. First compare your complete workflow inputs and settings. If they are identical, do not assume a reference-control or LoRA node is responsible for the difference. Keep example outputs when comparing changes, since a single run may not represent the full range of results.
Frequently asked questions
Do I need the extended backend for every workflow?
No. The documented basic and standard enhancer features use the community-maintained Vitoom Nunchaku backend. Direct K/V nodes and Identity Feature Transfer Final require the author's extended backend.
Are the enhancer nodes identical to the original Flux2Klein-Enhancer nodes?
No. The author describes their behavior as close, but not identical, and notes that the enhancer implementation is experimental.
Can I use several references?
Yes. The extension documents multi-reference editing for both 4B and 9B.
Can I combine several LoRAs?
Yes. You can chain ordinary LoRA Loader nodes or manage an ordered set with the Power LoRA Loader.
Is rgthree required for the Power LoRA Loader?
No. The author states that rgthree is not a runtime dependency.
Learn More about ComfyUI-Nunchaku-Klein
- ComfyUI: The workflow application in which the extension’s nodes are used.
- Official Nunchaku: The official project, separate from this extension.
- Community-maintained Vitoom Nunchaku backend: Background on the backend used for the documented standard features.
- Extended Vitoom Nunchaku backend: Information about the backend required for Direct K/V features and Identity Feature Transfer Final.
- ComfyUI-Flux2Klein-Enhancer: The related enhancer project. Remember that this extension’s adapted enhancer nodes are not exact equivalents.
The extension is licensed under GPL-3.0-or-later.
