Learn › ComfyUI Advanced: Training, Kontext, and Automation › FLUX Kontext: Instruction-Based Image Editing

FLUX Kontext: Instruction-Based Image Editing

Advanced 🕐 12 min Lesson 1 of 12
What you'll learn
  • Explain how FLUX Kontext instruction-based editing differs from img2img and standard FLUX generation
  • Download and place the four required model files for the local Kontext Dev workflow in ComfyUI
  • Load the FLUX Kontext Dev Image Edit template and run a first edit on an image
  • Write effective edit instructions using the six principles from the official ComfyUI documentation

A Different Approach to Image Editing

Standard FLUX text-to-image asks you to describe the final result: a woman in a red jacket standing in a forest. To get a variation with a blue jacket instead, you change the prompt and generate again — but you receive a completely new image, not an edit of the first one. The lighting shifts, the pose changes slightly, the background trees rearrange. You cannot precisely carry anything from the original into the new result.

FLUX Kontext works differently. You load an existing image, write an instruction about what to change — "change the jacket from red to blue" — and the model applies just that change while leaving the rest of the image intact. Same woman, same forest, same pose, same lighting. Only the jacket colour changes.

This is not img2img. Img2img re-generates the entire image at a reduced denoise value and cannot guarantee any specific element stays the same. Kontext understands the semantic content of your image — it recognises what a "jacket" is in context, locates it in the frame, and changes only that element. The 12-billion-parameter model was trained specifically to follow edit instructions while preserving unmentioned content, which is a fundamentally different capability.

The practical effect: you can iterate on an image across multiple editing passes, changing one thing at a time, without the rest of the image drifting. That changes how you plan creative work in ComfyUI.

Two Versions in ComfyUI

ComfyUI supports FLUX Kontext in two distinct ways, and knowing which one you are using determines your setup path:

  • FLUX.1 Kontext Dev (local model): A 12B-parameter diffusion transformer that runs entirely on your machine. Downloaded as a safetensors file, used like any other FLUX checkpoint. Free under the FLUX.1 Non-Commercial License. Requires approximately 12–16 GB VRAM at fp8 precision. This is the version this lesson covers — it gives you full workflow flexibility, LoRA compatibility, and no per-generation cost.
  • Kontext Pro and Max (Partner Nodes): API-based versions that call Black Forest Labs' cloud service through your Comfy account. No local model files to manage. Billed per generation in Comfy credits. Kontext Pro handles editing and composing; Kontext Max adds higher prompt precision and typography support. Use these if you want maximum quality without the VRAM requirement, or if you are on a machine where local generation is not practical.

The local dev version trades some output quality for complete control: you can combine it with LoRAs (covered in Lesson 2), adjust sampler settings, and integrate it into larger multi-step workflows. The API versions are faster and produce sharper results but are less customisable. Both are legitimate tools — the choice comes down to your hardware and whether you need workflow flexibility or raw output quality.

Setting Up the Local Kontext Dev Workflow

Four model files are required. Download each and place it in the specified folder inside your ComfyUI installation:

  • flux1-dev-kontext_fp8_scaled.safetensors (the diffusion model) → ComfyUI/models/diffusion_models/
    Source: Hugging Face — search for Comfy-Org/flux1-kontext-dev_ComfyUI
  • ae.safetensors (VAE) → ComfyUI/models/vae/
    Source: same repository. If you already have FLUX installed locally, you very likely have this file — check before downloading again.
  • clip_l.safetensors (text encoder) → ComfyUI/models/text_encoders/
    Source: Hugging Face — comfyanonymous/flux_text_encoders
  • t5xxl_fp8_e4m3fn_scaled.safetensors (T5 text encoder) → ComfyUI/models/text_encoders/
    Source: same repository. Use the fp16 version instead if your GPU has 20 GB or more VRAM — it is more accurate but larger.

Once the files are in place, update ComfyUI to the latest version (the Kontext Dev nodes require a recent build), then restart. Load the built-in template by going to Workflow → Browse Templates → Flux and selecting FLUX Kontext Dev Image Edit. This gives you a complete, correctly wired graph to start from rather than building it manually from scratch.

What the Workflow Looks Like

The Kontext Dev template uses the same core nodes as a regular FLUX text-to-image graph, with one critical addition:

  • Load Diffusion Model: Select flux1-dev-kontext_fp8_scaled.safetensors from the dropdown. This node loads the 12B model weights.
  • DualCLIP Load: Confirm clip_l.safetensors and your T5 file are selected. These are the two text encoders that process your instruction.
  • Load VAE: Select ae.safetensors. The VAE encodes and decodes between pixel space and latent space.
  • Load Image: This is the addition. Load the image you want to edit here. The node also lets you load from the output directory, which makes it straightforward to feed the result of one edit into the next round.
  • CLIP Text Encode: Write your edit instruction here. Note that there is no negative prompt node — Kontext does not use negative conditioning.
  • KSampler / SamplerCustomAdvanced: Keep CFG at 1.0. Kontext uses the same guidance mechanism as regular FLUX dev and ignores CFG values above 1.0. Use the template defaults for steps and sampler to start.
  • Save Image: Output lands in ComfyUI/output/ as usual.

The key architectural difference from standard FLUX: the input image is VAE-encoded and passed into the conditioning pipeline alongside your text instruction. The model sees both simultaneously — the pixels of your source image and your instruction — and generates an output that incorporates the instruction while maintaining everything that was not mentioned. This is why the node graph looks almost identical to a regular FLUX workflow but produces completely different behaviour.

Writing Effective Edit Instructions

Switching from "describe the final image" to "describe the change" is a bigger mental shift than it initially sounds. These six principles, drawn directly from the official ComfyUI Kontext documentation, produce consistently accurate edits:

  1. Name the subject precisely. "The woman with short black hair" produces more reliable results than "her" or "the person." The more specifically you identify what to change, the less likely the model is to alter the wrong element. Use visual identifiers — clothing, hair colour, position in frame — rather than assumed context.
  2. Say what to leave unchanged. Add phrases like "keep the facial features, pose, and background unchanged." This is not redundant — it actively signals to the model which parts of the image are not up for reinterpretation. For edits to a subject's clothing, adding "preserve the face and background exactly" routinely produces cleaner results than omitting it.
  3. Use precise action verbs. "Change the jacket to blue" and "replace the cloudy sky with a clear sunset" are specific. "Transform the scene" or "make it more vibrant" are vague — the model fills in gaps with its own interpretation, which frequently overshoots. "Change," "replace," "add," and "remove" are the verbs that produce predictable behaviour.
  4. One change per run. Trying to change the background, recolour the clothing, and adjust the lighting in a single prompt usually produces compromised results across all three. Make one edit, evaluate the output, then load that output as the input for the next change. The iterative loop is the intended workflow, not a workaround for a limitation.
  5. Describe styles by their visual properties. Instead of "make it a sketch," write "convert to a pencil sketch with visible hatching and fine crosshatching lines on shadows." Instead of "make it cinematic," write "apply a blue-teal colour grade with crushed blacks and slightly lifted highlights." Naming the visual properties directly gives the model a specific target rather than a category to interpret.
  6. Wrap text edits in quotes. To change text visible in an image — a sign, label, or title — write: Replace 'Hello' with 'Welcome', keeping the same font style and size. Putting both the original and replacement text in single quotes consistently improves accuracy for these edits.

What Kontext Handles Well and Where It Struggles

Understanding the model's reliable strengths helps you plan editing workflows around them rather than discovering limits mid-project.

Kontext is reliable for: changing background environments (swapping an indoor scene for an outdoor one, changing the time of day or weather), recolouring or restyling clothing, applying art style treatments to photographs (watercolour, oil painting, pencil sketch), replacing short text in signs or logos, adding simple objects to backgrounds, and adjusting colour grading across the whole image.

Kontext struggles with: replacing a person's face or changing their identity, making large compositional changes (moving the main subject to a different position in the frame), adding complex new objects with specific geometry that did not exist in the original, and very fine typographic work beyond simple text substitution. For any of these, starting fresh with a new generation and using ControlNet for structure is usually the more reliable path.

These limits are a direct consequence of what the model was trained for. Kontext was designed for targeted, local edits to existing content — not for full scene reconstruction. Knowing the boundary keeps you from spending time on edit instructions that the model architecture cannot reliably deliver.

The Iterative Editing Loop

The most effective way to work with Kontext is to treat it as a multi-step process rather than a single-shot operation. Start with your source image, make one targeted change, evaluate the result, then load that result as the input for the next edit. Each pass is small and controlled, which prevents errors from compounding across a long editing session.

ComfyUI's Load Image node supports this directly: it can browse the output directory, so you can select your latest result and immediately queue the next edit without leaving the application. If a particular step produces an unwanted change, the previous output is still saved in the output folder — you can go back to any prior step rather than starting from scratch.

Branching also works well with this approach: save a copy of an intermediate result, then apply two different instructions from the same starting point and compare them side by side. Because each edit is cheap to run compared to a full generation, exploring alternatives at each step is practical in a way it is not with standard text-to-image workflows.

Lesson 2 builds on this foundation by adding FLUX Kontext to multi-image character consistency workflows — using a reference character image alongside an instruction to keep that character's identity consistent across many different scenes and compositions.

Key takeaways
  • FLUX Kontext takes both an image and an edit instruction simultaneously — it changes only what the instruction describes while leaving everything else intact, which is different from img2img re-generation
  • The local dev model (flux1-dev-kontext_fp8_scaled.safetensors) goes in diffusion_models/ and requires 12-16 GB VRAM at fp8 precision; Kontext Pro and Max are API alternatives billed via Comfy credits
  • Effective Kontext prompts are instructions not descriptions — write 'change the jacket to blue' not 'woman wearing a blue jacket'
  • Editing one element per run and reusing the output as the next input consistently produces cleaner results than trying to combine multiple changes in a single prompt
  • Adding 'keep the facial features, pose, and background unchanged' to your instruction actively protects parts of the image you do not want altered — it is not redundant
Learn more every week Get 5 hand-picked prompts + new AI tools every Monday. Free.