Release 0.14.2

📊 Improved Metadata Handling

• Enhanced IPTC & XMP Support: Significant improvements to metadata reading and writing, ensuring better compatibility with professional image editing tools.
• Robust Metadata Extraction: Refined logic for extracting generation parameters from previously generated images.
• New Metadata Tests: Added comprehensive test suite for IPTC metadata building and original image info utilities.

🤖 DX & Maintenance

• Cursor AI Workflows: Introduced standardized Cursor commands and agent rules in .cursor/ for improved development consistency and automation.
• SeedVR2 & ControlNet Tweaks: Minor refinements to SeedVR2 and ControlNet model implementations.
• Documentation Updates: Updated README and added AGENTS.md for better contributor onboarding.

---

Release 0.14.1

🔧 SeedVR2 Improvements

• Enhanced Color Correction: Implemented precise LAB histogram matching with wavelet reconstruction for superior color consistency between input and upscaled images.
• Configurable Softness: Added a new --softness parameter (0.0 to 1.0) to control input pre-downsampling, allowing for smoother upscaling results when desired.
• RoPE Alignment: Fixed RoPE dimension mismatch (increased to 128) to perfectly match the reference 3B transformer architecture.

🤖 DX & Maintenance

• Updated .cursorrules: Added standard procedure for test output preservation and release management.
• Updated Test Infrastructure: Updated SeedVR2 reference images and fixed dimension-related test failures.

---

Release 0.14.0

🎨 New Model Support

• SeedVR2 Diffusion Upscaler: Added support for SeedVR2, a powerful diffusion-based image upscaler.
• New command: mflux-upscale-seedvr2 for high-quality image upscaling.
• Tiling support: Tiling is enabled by default for SeedVR2 to support high-resolution upscaling on standard memory configurations.

🔧 Improvements

• Global VAE Tiling Support: Introduced a unified VAE tiling system (VAETiler) that supports both tiled encoding and decoding.
• Low-RAM Mode Enhancements: Enabling --low-ram now automatically activates VAE tiling across all model families (Flux, Qwen, FIBO, Z-Image), significantly reducing memory pressure for high-resolution generation on Apple Silicon.
• Robust Offline Cache Handling: Improved logic for detecting complete cached models on HuggingFace Hub, handling symlinks and missing files more reliably to prevent runtime errors during offline use.
• Selective Weight Loading: Support for loading specific weight files, enabling more flexible model configurations and better resource sharing between related models.
• CLI UX Improvements:
  • Multi-image generation (multiple seeds or input images) now automatically appends suffixes (_seed_{seed} or _{image_name}) to output filenames to prevent accidental overwrites.
  • Better model configuration resolution with a priority-based system for resolving ambiguous model names.
• Enhanced Shell Completions: Significant updates to shell completion generation to support new commands and properly handle positional arguments and subparsers.
• Qwen Test Hardening: Updated Qwen image generation and edit tests to use 8-bit quantization for more robust and faster testing.
• Test Infrastructure: Added automatic MLX version pinning (v0.29.2) in make test-fast to ensure consistent test environments across different development setups.

📝 Documentation

• Added information about pre-quantized models available on HuggingFace for easier access.

---

Release 0.13.3

🐛 Bug Fixes

• LoRA save bloat prevention: Bake and strip LoRA wrappers before sharding to avoid exploding shard counts/sizes when saving quantized models with multiple/mismatched LoRAs (see issue #217 comment).
• Regression test hardening: LoRA model-saving tests now include size guardrails (5% tolerance) while using the bundled local LoRA fixtures to catch shard bloat regressions early.

---

Release 0.13.2

✨ Improvements

• Better error messages for multi-file LoRA repos: When a HuggingFace LoRA repo contains multiple .safetensors files, the error message now displays copy-paste ready options instead of a raw list
• Z-Image LoRA format support: Added support for Kohya and ComfyUI LoRA naming conventions, enabling compatibility with more community LoRAs.

---

Release 0.13.1

🐛 Bug Fixes

• FIBO VLM chat template not loaded: Fixed issue where the FIBO VLM tokenizer's chat template was not being loaded with transformers v5, causing apply_chat_template() to fail. The tokenizer loader now properly extracts and sets the chat template from the tokenizer config.

---

Release 0.13.0

MFLUX v.0.13.0 Release Notes

🎨 New Model Support

• Z-Image Turbo Support: Added support for Z-Image Turbo, a fast distilled Z-Image variant optimized for speed
• New command: mflux-generate-z-image-turbo for rapid image generation (with LoRA support, img2img, and quantization)

✨ New Features

• FIBO VLM Quantization Support: The FIBO VLM commands (mflux-fibo-inspire, mflux-fibo-refine) now support quantization via the -q flag (3, 4, 5, 6, or 8-bit)

• Unified --model argument: The --model flag now accepts local paths, HuggingFace repos, or predefined model names

  • Local paths: --model /Users/me/models/fibo-4bit or --model ~/my-model
  • HuggingFace repos: --model briaai/Fibo-mlx-4bit
  • Predefined names: --model dev, --model schnell, --model fibo
  • This mirrors how LoRA paths work for a consistent UX

• Scale Factor Dimensions for Img2Img: Generalized the scale factor feature (e.g., 2x, 0.5x, auto) from upscaling to all img2img commands

  • Specify output dimensions relative to input image: --width 2x --height 2x
  • Use auto to match input image dimensions: --width auto --height auto
  • Mix scale factors with absolute values: --width 2x --height 512
  • Supported in: mflux-generate, mflux-generate-z-image-turbo, mflux-generate-fibo, mflux-generate-kontext, mflux-generate-qwen

• DimensionResolver utility: New DimensionResolver.resolve() for consistent dimension handling across commands

🔧 Architecture Improvements

• Unified Resolution System: New resolution/ module for consistent parameter resolution across all models
  • PathResolution: Resolves model paths from local paths, HuggingFace repos, or predefined names
  • LoRAResolution: Handles LoRA path resolution from all supported formats
  • ConfigResolution: Centralizes configuration resolution logic
  • QuantizationResolution: Determines quantization from saved models or CLI args
• Unified Weight Loading System: Complete rewrite of weight handling with declarative mappings
  • New WeightLoader with single load(model_path) interface
  • WeightDefinition classes define model structure per model family
  • WeightMapping declarative mappings replace imperative weight handlers
  • Removed all per-model weight_handler_*.py files in favor of unified system
• Unified Tokenizer System: New common tokenizer module
  • TokenizerLoader.load_all() with unified model_path interface
  • Removed model-specific tokenizer handlers (clip_tokenizer.py, t5_tokenizer.py, etc.)
• Unified LoRA API: Simplified LoRA loading to a single lora_paths parameter
  • All LoRA formats now resolved through LoRALibrary.resolve_paths():
    • Local paths: /path/to/lora.safetensors
    • Registry names: my-lora (from LORA_LIBRARY_PATH)
    • HuggingFace repos: author/model
    • New: HuggingFace collections: repo_id:filename.safetensors
  • Simplified model initialization: just pass lora_paths and everything resolves automatically
• Unified Latent Creator Interface: Standardized unpack_latents(latents, height, width) signature across all model families
  • FluxLatentCreator, ZImageLatentCreator, FiboLatentCreator, and QwenLatentCreator now share the same interface
  • Moved FIBO._unpack_latents to FiboLatentCreator.unpack_latents for consistency
• StepwiseHandler Refactor: Fixed StepwiseHandler to work with all model types by accepting a latent_creator parameter
  • Previously hardcoded to FluxLatentCreator, now model-agnostic
  • Each command passes its appropriate latent creator to CallbackManager.register_callbacks()
• CLI Reorganization: Moved CLI entry points to model-specific directories (e.g., mflux/models/flux/cli/)

🔄 Breaking Changes

• Simplified generate_image() API (programmatic users only):
  • Removed Config class - parameters are now passed directly to generate_image()
  • Removed RuntimeConfig class - internal complexity eliminated
  • Added Flux1 export to main mflux module for cleaner imports
• LoRA API simplified (programmatic users only):
  • Removed lora_names and lora_repo_id parameters from all model classes (Flux1, QwenImage, QwenImageEdit, etc.)
  • Removed --lora-name and --lora-repo-id CLI arguments
  • Removed LoRAHuggingFaceDownloader class

🔄 Breaking Changes (CLI)

• --path flag removed: The deprecated --path flag for loading models has been removed. Use --model instead for local paths, HuggingFace repos, or predefined model names.

📦 Dependency Updates

• Updated huggingface-hub from >=0.24.5,<1.0 to >=1.1.6,<2.0
  • v1.1.6 includes fix for incomplete file listing in snapshot_download which could cause cache corruption
  • Removed explicit accelerate and filelock dependencies (pulled in as transitive dependencies)
• Updated transformers from >=4.57,<5.0 to >=5.0.0rc0,<6.0
  • Required for huggingface-hub 1.x compatibility
  • Added workaround for Qwen2Tokenizer bug in transformers 5.0.0rc0 where vocab/merges files are not loaded correctly via from_pretrained()

🐛 Bug Fixes

• Qwen empty negative prompt crash: Fixed crash when running Qwen models without a --negative-prompt argument. Empty prompts now use a space as fallback to ensure valid tokenization.

• --model flag not working: Fixed bug where the --model argument wasn't being used for loading models from HuggingFace or local paths. All CLI commands now correctly use --model for model path resolution.

• Model Saving Index File: Fixed issue where locally saved models (via mflux-save) would fail to load when uploaded to HuggingFace, due to missing model.safetensors.index.json. The model saver now generates this index file alongside the safetensor shards, ensuring compatibility with both mflux and standard HuggingFace loading paths. (see #285)

🧪 Test Infrastructure

• Test markers: Added fast and slow pytest markers to categorize tests
  • Fast tests: Unit tests that don't generate images (parsers, schedulers, resolution, utilities)
  • Slow tests: Integration tests that generate actual images and compare to references
• New Makefile targets:
  • make test-fast - Run fast tests only (quick feedback during development)
  • make test-slow - Run slow tests only (image generation tests)
  • make test - Run all tests (unchanged)
• Run specific test categories: pytest -m fast or pytest -m slow
• GitHub Actions CI: Fast tests now run automatically on PRs and pushes to main

🔧 Internal Changes

• Simplified WeightLoader.load() to take a single model_path parameter instead of separate repo_id and local_path
• Simplified TokenizerLoader.load_all() with the same unified model_path interface
• Renamed local_path parameter to model_path in all model constructors for clarity
• Removed quantization_util.py - quantization now handled through QuantizationResolution
• Removed lora_huggingface_downloader.py - downloading integrated into LoRAResolution
• Added comprehensive test coverage for resolution modules

👩‍💻 Contributors

• Filip Strand (@filipstrand): Z-Image Turbo support, architecture improvements, core development

---

Release 0.12.1

🐛 Bug Fixes

• FIBO VLM Tokenizer Download: Fixed an issue where the FIBO VLM tokenizer files would not download automatically when the model weights were cached but tokenizer files were missing. The initializer now properly checks for tokenizer file existence and downloads them if needed.

---

Release 0.12.0

MFLUX v.0.12.0 Release Notes

🎨 New Model Support

• Bria FIBO Support: Added support for FIBO, the first open-source JSON-native text-to-image model from Bria.ai
• Three operation modes: Generate (text-to-image with VLM expansion), Refine (structured prompt editing), and Inspire (image-to-prompt extraction)
• New commands:
  • mflux-generate-fibo - Generate images from text prompts with VLM-guided JSON expansion
  • mflux-refine-fibo - Refine images using structured JSON prompts for targeted attribute editing
  • mflux-inspire-fibo - Extract structured prompts from reference images for style transfer and remixing
• VLM-guided JSON prompting: Automatically expands short text prompts into 1,000+ word structured schemas using a fine-tuned Qwen3-VL model

🔧 Restructure and 🔄 Breaking Changes

• Common module reorganization: Moved shared functionality to models/common/ for better code reuse
  • Unified latent creators across model families
  • Centralized scheduler implementations
  • Common quantization utilities
  • Shared model saving functionality

👩‍💻 Contributors

• Filip Strand (@filipstrand): FIBO model implementation, architecture, core development

---

Release 0.11.1

MFLUX v.0.11.1 Release Notes

🎨 New Model Support

• Qwen Image Edit Support: Added support for the Qwen Image Edit model, enabling natural language image editing capabilities
• New command: mflux-generate-qwen-edit for image editing with text instructions
• Multiple image support: Edit images using multiple reference images via --image-paths parameter
• Model: Uses Qwen/Qwen-Image-Edit-2509 for high-quality image editing
• Quantization support: Full support for quantized models (8-bit recommended for optimal quality)

🔧 Improvements

• Dedicated Qwen Image command: Added mflux-generate-qwen as a dedicated command for Qwen Image model generation. The mflux-generate command now only supports Flux models.
• Image comparison utility refactoring: Refactored image_compare.py into a cleaner class-based structure with static methods
• Error handling: Moved ReferenceVsOutputImageError to the main exceptions module for better organization

🔄 Breaking Changes

⚠️ Qwen Image Command Change: The Qwen Image model now requires using the dedicated mflux-generate-qwen command instead of mflux-generate --model qwen. This provides better separation between Flux and Qwen model families and improves command clarity.

👩‍💻 Contributors

• Filip Strand (@filipstrand): Qwen Image Edit model implementation, code refactoring

---