mflux

0.23.0

New

• mflux-generate-flux3 and mflux-generate-flux3-edit now run FLUX 3 Image Klein (distilled and Base), with text-to-image, editing with up to ten reference images, and 4, 6 and 8 bit quantization. (#878)
• mflux-generate-flux3 and mflux-generate-flux3-edit now load FLUX 3 Image Klein LoRAs with --lora, in the ComfyUI/ai-toolkit (BFL), diffusers/PEFT and kohya key formats. (#881)
• mflux-generate-qwen-2.1, -edit and -controlnet now run Qwen-Image-2.1-Turbo in 8 steps (--model qwen-image-2.1-turbo). mflux-save now writes one Qwen-Image-2.1 checkpoint that both the text-to-image and edit commands load. (#859)
• New command mflux-generate-krea2-controlnet: Krea 2 Turbo with a depth ControlNet. Give it a photo (Depth Pro estimates the depth) or a ready-made depth map. LoRAs and -q work as in mflux-generate-krea2. (#864)

Improved

• Built-in models now load from a pinned HuggingFace commit, so every install runs the same weights. A model cached from another commit needs one online run to switch; the weights already on disk are reused. (#872)
• Qwen Image 2.1’s fused attention prologue now handles strided projections and preserves MLX RMSNorm precision and rounding while producing the attention layout directly. Generated pixels may differ from the previous fused implementation; unsupported configurations retain the composed path. (#846)
• Qwen Image 2.1 packs compatible dense attention and feed-forward projections during generation, reducing projection overhead while preserving checkpoint compatibility. Quantized and adapter-bearing projections retain their original path. (#847)

Changed

• Image saving now fails the run when the output file cannot be written (permission error, full disk, missing volume) instead of logging the error and exiting 0. (#861)

Docs

• The Qwen-Image-2.1 README now documents mflux-generate-qwen-2.1-controlnet: control types, Turbo, inpainting with a mask, and how to size the control image. (#880)
• The README entry for mlx-teacache now names the models where it skips steps: FLUX.1 dev and Krea, FLUX.2 Klein base, Z-Image base and Qwen-Image (original checkpoint). (#855)
• docs/plugins.md tells how to find, install and write a plugin that adds commands under mflux.extras. The README links to it. (#856)

Internal

• The new /mflux-pr-docs agent skill writes the PR body and the release note for the developer to approve. Update skills for Claude Code, Cursor & GitHub Copilot in .claude/skills/. (#837)
• /mflux-pr-docs now passes a developer-approved title to gh pr create, so it works from Claude Code. An open PR keeps its title unless the developer changes it. (#854)
• Golden test references regenerated for Krea 2, Qwen-Image, Qwen-Image-2.1, FIBO lite and ERNIE-Image, and the golden test helper fixed for FIBO Edit and HuggingFace LoRA ids. Generated images don't change. (#871)

0.22.0

Improved

• mflux-generate-krea2, mflux-generate-lens, mflux-generate-boogu and mflux-generate-ideogram4 now expose validate, load and generate for Python callers. (#821)
• mflux-generate-qwen and mflux-generate-qwen-edit now expose validate, load and generate for Python callers, and stop with an error when --model names another model instead of ignoring it. (#836)

Fixed

• mflux-generate-z-image and mflux-generate-ernie-image now keep a scheduler given as --scheduler=NAME. Before, that spelling was replaced by the command's default scheduler. (#849)

Changed

• Z-Image runs its transformer in bfloat16 instead of float32. Denoising is about 30% faster on an M5, and images for the same seed change slightly. Add --float32 to reproduce an image from an older release. (#803)
• Z-Image now writes a warning when a prompt fills the 512-token limit. Before, the model ignored the extra text with no message. (#810)
• LoRA training: a new adapter now starts with lora_B at zero, so step 0 is the base model. Before, each new adapter added a random change to every patched layer, which caused a grid pattern in the step-0 preview. (#811)
• FLUX.2 klein, Z-Image and Qwen-Image 2.1 take a new opt-in --compute-precision float16 (compute_precision=mx.float16 in Python) that runs only the attention and feed-forward layers in float16. On an M1 Max it made each step 8–35% faster and a whole generation 7–29% faster, at the same peak memory; the image for a given seed changes slightly. It is off by default. (#820)
• Update urllib3 to 2.8.0 or later to fix HTTPS proxy TLS and streamed-response denial-of-service vulnerabilities. (#822)
• A LoRA baked into a model quantized at load (-q) on FLUX, FLUX.2, Qwen-Image, Krea 2 and Z-Image now has the same effect as the live adapter. It used to lose part of it, about 20% for a weak LoRA at scale 0.5 on q8. Layers below 8 bits keep their bits instead of being re-quantized at q8. (#824)
• Loading a SeedVR2 model saved with mflux-save no longer warns that the folder "contains no files matching" the original file names. (#828)
• Add Schedulers documentation (#829)
• mflux-generate-qwen-2.1 and mflux-generate-qwen-2.1-edit no longer read every weight into memory at load. For an 8-bit model at 512x512 the peak drops from about 24 GB to about 13 GB, and --low-ram brings it to about 8 GB again in most runs. (#833)
• mflux-generate-qwen-2.1-edit --scheduler now reaches the edit (it was checked, then ignored), and --enhance-prompt rewrites with every reference image instead of only the first. QwenImage21Edit gains rewrite_prompt() and a scheduler argument, and takes PIL images in image_paths. Both Qwen-Image-2.1 commands record a scheduler other than linear, so --config-from-conf replays it. (#835)
• Require fsspec 2026.6.0 or later, which fixes a code execution vulnerability in its ReferenceFileSystem (GHSA-27vj-qcqg-25rc). mflux doesn't use fsspec directly. (#838)
• FLUX.1, FIBO and Qwen-Image load the bias of their last normalization layer again. mflux 0.16.0 to 0.21.0 dropped it, so their images change: slightly for FLUX.1, visibly for Qwen-Image. A model saved with those versions generates as before; save it again from the original weights to include the bias. (#839)
• New command mflux-generate-qwen-2.1-controlnet: Qwen-Image-2.1 with Alibaba's Fun ControlNet Union. One checkpoint takes Canny, depth, pose and five more kinds of control image, and inpaints through the same branch with --image-path and --mask-image. (#842)
• The Qwen-Image-2.1 edit's step cache no longer skips steps in runs under 10 steps, such as the 6-step viggle_turbo schedule, where skipping changed the image noticeably. Baking a LoRA now warns when the baked weights hold less than 90% of its update, and suggests --no-bake-lora. (#843)
• Qwen-Image-Edit-2511 runs as itself: mflux-generate-qwen-edit --model qwen-image-edit-2511 (or qwen-edit-2511) loa

0.21.0

Added

• Qwen-Image-2.1 now supports instruction-based editing with up to ten reference images, RGBA output, and prefix KV caching through mflux-generate-qwen-2.1-edit. The new QwenImage21Edit Python API can quantize and export complete vision-capable checkpoints; the existing generation command and text-only exports remain available. (#741)
• Logging is now configured at CLI boot; use --verbose to make it more verbose. (#747)
• Qwen-Image-2.1 edit: new --mask-image, --auto-mask, --strength, --enhance-prompt, --verify and --use-step-cache options for mflux-generate-qwen-2.1-edit. They give masked edits, automatic object masks, subtler edits, prompt rewrite, a self-check with retries, and faster runs. (#749)
• Added Qwen Image 2.1 LoRA support for PEFT .default adapters via --lora. (#756)
• Qwen-Image-2.1: new --scheduler viggle_turbo for mflux-generate-qwen-2.1 and mflux-generate-qwen-2.1-edit. With Viggle's distilled turbo LoRA and --steps 6, it generates and edits in 6 steps instead of 40. (#764)
• New model: inclusionAI Ming-Image-0.1-Design (mflux-generate-ming), a design-focused text-to-image model with RGBA output; its 16B MoE text encoder can be quantized separately with --text-encoder-quantize. (#765)
• Qwen Image 2.1 now accepts common transformer. and diffusion_model. LoRA exports, including fused gate_up weights and modulation/timestep embedding adapters. (#768)
• Z-Image now loads ComfyUI LoRAs with fused QKV projections and normalization/bias deltas. Adapters containing direct deltas require the default baked inference mode. (#772)
• Support independently installed mflux namespace extensions, enabling community mflux.web UI packages to coexist across editable checkouts and separate import directories. (#776)
• Qwen-Image-2.1 reference editing now supports LoRA adapters through the same mappings as text-to-image, including baking controls and metadata replay. Both commands share the Transformer core and component-loading mechanism while retaining compatibility with existing model exports. (#777)
• mflux-generate-z-image-turbo now exposes ZImageTurboCommand.load and ZImageTurboCommand.generate, so Python code can load the model once and generate many images with the command's own flag handling. (#780)
• mflux-generate-z-image and mflux-generate-z-image-controlnet now expose load and generate for Python callers, and all three Z-Image commands add validate, which checks a request without loading weights. (#785)
• mflux-save can now save the SeedVR2 3B and 7B upscalers. mflux-upscale-seedvr2 --model <dir> reads the variant from the saved weights. (#800)
• mflux-generate-ernie-image-turbo and mflux-generate-ernie-image now expose validate, load and generate for Python callers. (#815)

Improved

• Qwen-Image-2.1 generates up to ~1.8x faster: denoise steps run ~12% faster (cached text prefix, bounded to the two most recent embeddings; fused Q/K norm+rope Metal kernel, disable with MFLUX_QWEN21_DISABLE_FUSED_PROLOGUE=1), and generate_image(..., teacache_ratio=0.25) reuses the previous noise on the least-changing steps for a further 1.4x (1.77x at 0.4). (#778)
• Qwen Image 2.1's step reuse is now --step-cache-ratio (--teacache-ratio still works) and the ratio is recorded in image metadata and replayed by --config-from-conf. The logic is shared (mflux.models.common.step_cache.StepCache) so other models can adopt it. (#779)
• MFlux now imports OpenCV and PyTorch only in the code paths that use them. Commands that do not use these libraries start without them. (#787)
• LoRA and LoKr adapters now run in the precision the model was loaded in, not float32. Training and LoRA inference on bfloat16 models use less memory and run faster. (#801)

Fixed

• bump anyio due to CVE-2026-63374 & CVE-2026-64847. MFlux doesn't import it directly - it is used transitively by httpx through huggingface-hub (#744)
• mflux now refuses a checkpoint whose wei

0.20.0

Changed

• Fix Z-Image producing a different image for the same seed when other code (a preview callback, another library) had run the model earlier in the same process. (#715)
• mflux-generate-lens --low-ram no longer crashes with an AttributeError after the model has loaded. (#725)
• In-loop callbacks can opt in to the model's per-step predicted image: declare a denoised parameter in call_in_loop and Krea 2 passes it alongside the noisy latents. Callbacks with the existing signature are unaffected; other models pass nothing yet. (#729)
• The mflux_version recorded in image metadata and training checkpoints is mflux's own version again when mflux is installed as a dependency of another project; it used to report the host project's version. (#728) (#732)
• mflux-generate-z-image-controlnet: --controlnet-strength now defaults to 1.0, so the strength given in each --control spec is the scale the model sees (it used to be multiplied by 0.4, and a 0.85 control ran at 0.34, too weak to follow the hint). The Z-Image README now documents the ControlNet command. (#721) (#733)
• --vae-tiling and --low-ram now tile the final VAE decode on Krea 2 and Boogu, where the flag was accepted and ignored, cutting the decode at 1024 px from about 7 GB to about 3 GB. FLUX.2 Klein, Klein edit, Lens and Ideogram 4 tile only when you ask with --vae-tiling: their shared decoder takes its normalisation statistics per tile, which shifts colour between tiles, so low-RAM leaves them untiled. (#735)
• New model: Qwen-Image-2.1 (Qwen/Qwen-Image-2.1) — 7.1B single-stream block-causal DiT with a Qwen3-VL text encoder and a 64-channel causal VAE. Available as mflux-generate-qwen-2.1 with txt2img, img2img, optional true CFG, and -q 8/-q 4 quantization (text encoder stays bf16). 40-step guidance-free sampling by default. (#736)
• n/a for version bump PRs (#738)