mflux

A MLX port of FLUX based on the Huggingface Diffusers implementation.

About

Run the powerful FLUX, Qwen Image, FIBO, and Z-Image models locally on your Mac!

Table of contents

• Philosophy
• 💿 Installation
• 🖼️ Generating an image
  • 📜 Full list of Command-Line Arguments
• ⏱️ Image generation speed (updated)
• ↔️ Equivalent to Diffusers implementation
• 🗜️ Quantization
• 💽 Running a model directly from disk
• 🌐 Third-Party HuggingFace Model Support
• 🎨 Image-to-Image
• 🦙 Qwen Models
  • 🖼️ Qwen Image
  • ✏️ Qwen Image Edit
• 🌀 FIBO
• ⚡ Z-Image
• 🔌 LoRA
• 🎭 In-Context Generation
  • 📸 Kontext
  • 🎨 In-Context LoRA
  • 👕 CatVTON (Virtual Try-On)
  • ✏️ IC-Edit (In-Context Editing)
• 🛠️ Flux Tools
  • 🖌️ Fill
  • 🔍 Depth
  • 🔄 Redux
• 🕹️ Controlnet
• 🔎 Upscale
• 🎛️ Dreambooth fine-tuning
• 🧠 Concept Attention
• 🚧 Current limitations
• 💡Workflow tips
• 🔬 Cool research
• 🌱‍ Related projects
• 🙏 Acknowledgements
• ⚖️ License

Philosophy

MFLUX is a line-by-line port of the FLUX, Qwen, Bria and Z-Image models implementations in the Huggingface Diffusers and Huggingface Transformers libraries to Apple MLX. MFLUX is purposefully kept minimal and explicit - Network architectures are hardcoded and no config files are used except for the tokenizers. The aim is to have a tiny codebase with the single purpose of expressing these models (thereby avoiding too many abstractions). While MFLUX priorities readability over generality and performance, it can still be quite fast, and even faster quantized.

All models are implemented from scratch in MLX and only the tokenizers are used via the Huggingface Transformers library. Other than that, there are only minimal dependencies like Numpy and Pillow for simple image post-processing.

💿 Installation

For users, the easiest way to install MFLUX is to use uv tool: If you have installed uv, simply:

uv tool install --upgrade mflux --prerelease=allow

to get the mflux-generate and related command line executables. You can skip to the usage guides below.

mkdir -p mflux && cd mflux && python3 -m venv .venv && source .venv/bin/activate

pip install -U mflux

 git clone git@github.com:filipstrand/mflux.git

 make install

 make test

If you have trouble installing MFLUX, please see the installation related issues section.

# Install completions
mflux-completions

# Reload your shell
exec zsh

# Now try tab completion!
mflux-generate --

mflux-completions --check

🖼️ Generating an image

Run the command mflux-generate by specifying a prompt and the model and some optional arguments. For example, here we use a quantized version of the schnell model for 2 steps:

mflux-generate --model schnell --prompt "Luxury food photograph" --steps 2 --seed 2 -q 8

This example uses the more powerful dev model with 25 time steps:

mflux-generate --model dev --prompt "Luxury food photograph" --steps 25 --seed 2 -q 8

This example uses the qwen model with 20 time steps:

mflux-generate-qwen --prompt "Luxury food photograph" --steps 20 --seed 2 -q 6

You can also pipe prompts from other commands using stdin:

echo "A majestic mountain landscape" | mflux-generate --prompt - --model schnell --steps 2

This is useful for integrating MFLUX into shell scripts or dynamically generating prompts using LLM inference tools such as llm, mlx-lm, ollama, etc.

Alternatively, you can use MFLUX directly in Python:

from mflux.models.flux.variants.txt2img.flux import Flux1

# Load the model
flux = Flux1.from_name(
   model_name="schnell",  # "schnell", "dev", or "krea-dev"
   quantize=8,            # 3, 4, 5, 6, or 8
)

# Generate an image
image = flux.generate_image(
   seed=2,
   prompt="Luxury food photograph",
   num_inference_steps=2,  # "schnell" works well with 2-4 steps, "dev" and "krea-dev" work well with 20-25 steps
   height=1024,
   width=1024,
)

image.save(path="image.png")

For more advanced Python usage and additional configuration options, you can explore the entry point files in the source code, such as generate.py, generate_controlnet.py, generate_fill.py, and others in the src/mflux/ directory. These files demonstrate how to use the Python API for various features and provide examples of advanced configurations.

⚠️ If the specific model is not already downloaded on your machine, it will start the download process and fetch the model weights (~34GB for Schnell/Dev models, ~58GB for Qwen). See the quantization section for running compressed versions of the model. ⚠️

By default, mflux caches files in ~/Library/Caches/mflux/. The Hugging Face model files themselves are cached separately in the Hugging Face cache directory (e.g., ~/.cache/huggingface/).

To change the mflux cache location, set the MFLUX_CACHE_DIR environment variable. To change the Hugging Face cache location, you can modify the HF_HOME environment variable (e.g. to HF_HOME=/Volumes/T7/.cache/huggingface). For more details on Hugging Face cache settings, please refer to the Hugging Face documentation.

🔒 FLUX.1-dev currently requires granted access to its Huggingface repo. For troubleshooting, see the issue tracker 🔒

🎨 FLUX.1 Krea [dev]: Enhanced Photorealism

MFLUX now supports FLUX.1 Krea [dev], an 'opinionated' text-to-image model developed in collaboration with Krea AI. This model overcomes the oversaturated 'AI look' commonly found in generated images, achieving exceptional photorealism with distinctive aesthetics. This model can be used where the dev model is used, and it is available as krea-dev in MFLUX (also supports the alias dev-krea), this includes dreambooth fine-tuning.

mflux-generate \
    --model krea-dev \
    --prompt "A photo of a dog" \
    --steps 25 \
    --seed 2674888 \
    -q 8 \
    --height 1024 \
    --width 1024

Learn more about FLUX.1 Krea [dev] in the official announcement.

📜 Full list of Command-Line Arguments

# Scale by 2x in both dimensions
mflux-upscale --height 2x --width 2x --controlnet-image-path source.png

# Scale height by 1.5x, set width to specific pixels
mflux-upscale --height 1.5x --width 1920 --controlnet-image-path source.png

# Use auto (keeps original dimensions)
mflux-upscale --height auto --width auto --controlnet-image-path source.png

# Mix scale factors and absolute values
mflux-upscale --height 2x --width 1024 --controlnet-image-path source.png

# Generate 10 images using a prompt from a file
mflux-generate --prompt-file my_prompt.txt --auto-seeds 10

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "seed": {
      "type": ["integer", "null"]
    },
    "steps": {
      "type": ["integer", "null"]
    },
    "guidance": {
      "type": ["number", "null"]
    },
    "quantize": {
      "type": ["null", "string"]
    },
    "lora_paths": {
      "type": ["array", "null"],
      "items": {
        "type": "string"
      }
    },
    "lora_scales": {
      "type": ["array", "null"],
      "items": {
        "type": "number"
      }
    },
    "prompt": {
      "type": ["string", "null"]
    }
  }
}

{
  "model": "dev",
  "seed": 42,
  "steps": 8,
  "guidance": 3.0,
  "quantize": 4,
  "lora_paths": [
    "/some/path1/to/subject.safetensors",
    "/some/path2/to/style.safetensors"
  ],
  "lora_scales": [
    0.8,
    0.4
  ],
  "prompt": "award winning modern art, MOMA"
}

⏱️ Image generation speed (updated)

These numbers are based on the non-quantized schnell model, with the configuration provided in the code snippet below. To time your machine, run the following:

time mflux-generate \
--prompt "Luxury food photograph" \
--model schnell \
--steps 2 \
--seed 2 \
--height 1024 \
--width 1024

To find out the spec of your machine (including number of CPU cores, GPU cores, and memory, run the following command:

system_profiler SPHardwareDataType SPDisplaysDataType

Note that these numbers includes starting the application from scratch, which means doing model i/o, setting/quantizing weights etc. If we assume that the model is already loaded, you can inspect the image metadata using mflux-info image.png (or exiftool image.png) and see the total duration of the denoising loop (excluding text embedding).

These benchmarks are not very scientific and is only intended to give ballpark numbers. They were performed during different times with different MFLUX and MLX-versions etc. Additional hardware information such as number of GPU cores, Mac device etc. are not always known.

↔️ Equivalent to Diffusers implementation

There is only a single source of randomness when generating an image: The initial latent array. In this implementation, this initial latent is fully deterministically controlled by the input seed parameter. However, if we were to import a fixed instance of this latent array saved from the Diffusers implementation, then MFLUX will produce an identical image to the Diffusers implementation (assuming a fixed prompt and using the default parameter settings in the Diffusers setup).

The images below illustrate this equivalence. In all cases the Schnell model was run for 2 time steps. The Diffusers implementation ran in CPU mode. The precision for MFLUX can be set in the Config class. There is typically a noticeable but very small difference in the final image when switching between 16bit and 32bit precision.

Luxury food photograph

detailed cinematic dof render of an old dusty detailed CRT monitor on a wooden desk in a dim room with items around, messy dirty room. On the screen are the letters "FLUX" glowing softly. High detail hard surface render

photorealistic, lotr, A tiny red dragon curled up asleep inside a nest, (Soft Focus) , (f_stop 2.8) , (focal_length 50mm) macro lens f/2. 8, medieval wizard table, (pastel) colors, (cozy) morning light filtering through a nearby window, (whimsical) steam shapes, captured with a (Canon EOS R5) , highlighting (serene) comfort, medieval, dnd, rpg, 3d, 16K, 8K

A weathered fisherman in his early 60s stands on the deck of his boat, gazing out at a stormy sea. He has a thick, salt-and-pepper beard, deep-set blue eyes, and skin tanned and creased from years of sun exposure. He's wearing a yellow raincoat and hat, with water droplets clinging to the fabric. Behind him, dark clouds loom ominously, and waves crash against the side of the boat. The overall atmosphere is one of tension and respect for the power of nature.

Luxury food photograph of an italian Linguine pasta alle vongole dish with lots of clams. It has perfect lighting and a cozy background with big bokeh and shallow depth of field. The mood is a sunset balcony in tuscany.  The photo is taken from the side of the plate. The pasta is shiny with sprinkled parmesan cheese and basil leaves on top. The scene is complemented by a warm, inviting light that highlights the textures and colors of the ingredients, giving it an appetizing and elegant look.

🗜️ Quantization

MFLUX supports running FLUX in 3, 4, 5, 6, or 8-bit quantized mode. Running a quantized version can greatly speed up the generation process and reduce the memory consumption by several gigabytes. Quantized models also take up less disk space.

mflux-generate \
    --model schnell \
    --steps 2 \
    --seed 2 \
    --quantize 8 \
    --height 1920 \
    --width 1024 \
    --prompt "Tranquil pond in a bamboo forest at dawn, the sun is barely starting to peak over the horizon, panda practices Tai Chi near the edge of the pond, atmospheric perspective through the mist of morning dew, sunbeams, its movements are graceful and fluid — creating a sense of harmony and balance, the pond's calm waters reflecting the scene, inviting a sense of meditation and connection with nature, style of Howard Terpning and Jessica Rossier"

In this example, weights are quantized at runtime - this is convenient if you don't want to save a quantized copy of the weights to disk, but still want to benefit from the potential speedup and RAM reduction quantization might bring.

By selecting the --quantize or -q flag to be 4, 8, or removing it entirely, we get all 3 images above. As can be seen, there is very little difference between the images (especially between the 8-bit, and the non-quantized result). Image generation times in this example are based on a 2021 M1 Pro (32GB) machine. Even though the images are almost identical, there is a ~2x speedup by running the 8-bit quantized version on this particular machine. Unlike the non-quantized version, for the 8-bit version the swap memory usage is drastically reduced and GPU utilization is close to 100% during the whole generation. Results here can vary across different machines.

For systems with limited RAM, you can also use the --low-ram option which reduces GPU memory usage by constraining the MLX cache size and releasing text encoders and transformer components after use. This option is particularly helpful for preventing system memory swapping to disk on machines with less available RAM.

📊 Size comparisons for quantized models

The model sizes for both schnell and dev at various quantization levels are as follows:

4bit quantized model files are available for direct download on Hugging Face, eliminating the need to download full models and quantize them yourself.

💾 Saving a quantized version to disk

To save a local copy of the quantized weights, run the mflux-save command like so:

mflux-save \
    --path "/Users/filipstrand/Desktop/schnell_8bit" \
    --model schnell \
    --quantize 8

The mflux-save command works with both Flux and Qwen models.

Note that when saving a quantized version, you will need the original huggingface weights.

It is also possible to specify LoRA adapters when saving the model, e.g

mflux-save \
    --path "/Users/filipstrand/Desktop/schnell_8bit" \
    --model schnell \
    --quantize 8 \
    --lora-paths "/path/to/lora.safetensors" \
    --lora-scales 0.7

When generating images with a model like this, no LoRA adapter is needed to be specified since it is already baked into the saved quantized weights.

💽 Loading and running a quantized version from disk

To generate a new image from the quantized model, simply provide a --path to where it was saved:

mflux-generate \
    --path "/Users/filipstrand/Desktop/schnell_8bit" \
    --model schnell \
    --steps 2 \
    --seed 2 \
    --height 1920 \
    --width 1024 \
    --prompt "Tranquil pond in a bamboo forest at dawn, the sun is barely starting to peak over the horizon, panda practices Tai Chi near the edge of the pond, atmospheric perspective through the mist of morning dew, sunbeams, its movements are graceful and fluid — creating a sense of harmony and balance, the pond's calm waters reflecting the scene, inviting a sense of meditation and connection with nature, style of Howard Terpning and Jessica Rossier"

Note: When loading a quantized model from disk, there is no need to pass in -q flag, since we can infer this from the weight metadata.

Also Note: Once we have a local model (quantized or not) specified via the --path argument, the huggingface cache models are not required to launch the model. In other words, you can reclaim the 34GB diskspace (per model) by deleting the full 16-bit model from the Huggingface cache if you choose.

⚠️ * Quantized models saved with mflux < v.0.6.0 will not work with v.0.6.0 and later due to updated implementation. The solution is to save a new quantized local copy

If you don't want to download the full models and quantize them yourself, the 4-bit weights are available here for a direct download:

• For mflux < v.0.6.0:
  • madroid/flux.1-schnell-mflux-4bit
  • madroid/flux.1-dev-mflux-4bit
• For mflux >= v.0.6.0:
  • dhairyashil/FLUX.1-schnell-mflux-v0.6.2-4bit
  • dhairyashil/FLUX.1-dev-mflux-4bit
  • akx/FLUX.1-Kontext-dev-mflux-4bit
  • filipstrand/FLUX.1-Krea-dev-mflux-4bit
  • filipstrand/Qwen-Image-mflux-6bit
  • filipstrand/Z-Image-Turbo-mflux-4bit
  • briaai/Fibo-mlx-4bit
  • briaai/Fibo-mlx-8bit

Using the community model support, the quantized weights can be also be automatically downloaded when running the generate command:

mflux-generate \
    --model filipstrand/FLUX.1-Krea-dev-mflux-4bit \
    --base-model krea-dev \
    --prompt "A photo of a dog" \
    --steps 25 \
    --seed 2674888

mflux-generate-fibo \
    --model briaai/Fibo-mlx-4bit \
    --prompt-file ~/Desktop/bird.json \
    --width 1024 \
    --height 1024 \
    --steps 20 \
    --seed 42 \

💽 Running a model directly from disk

MFLUX supports running a model directly from a custom location using the --model flag with a local path. In the example below, the model is placed in /Users/filipstrand/Desktop/schnell:

mflux-generate \
    --model "/Users/filipstrand/Desktop/schnell" \
    --base-model schnell \
    --steps 2 \
    --seed 2 \
    --prompt "Luxury food photograph"

When loading from a local path, use --base-model to specify the architecture (e.g., schnell, dev).

Also note that unlike when using the typical alias way of initializing the model (which internally handles that the required resources are downloaded), when loading a model directly from disk, we require the downloaded models to look like the following:

.
├── text_encoder
│   └── model.safetensors
├── text_encoder_2
│   ├── model-00001-of-00002.safetensors
│   └── model-00002-of-00002.safetensors
├── tokenizer
│   ├── merges.txt
│   ├── special_tokens_map.json
│   ├── tokenizer_config.json
│   └── vocab.json
├── tokenizer_2
│   ├── special_tokens_map.json
│   ├── spiece.model
│   ├── tokenizer.json
│   └── tokenizer_config.json
├── transformer
│   ├── diffusion_pytorch_model-00001-of-00003.safetensors
│   ├── diffusion_pytorch_model-00002-of-00003.safetensors
│   └── diffusion_pytorch_model-00003-of-00003.safetensors
└── vae
    └── diffusion_pytorch_model.safetensors

This mirrors how the resources are placed in the HuggingFace Repo for FLUX.1. Huggingface weights, unlike quantized ones exported directly from this project, have to be processed a bit differently, which is why we require this structure above.

🌐 Third-Party HuggingFace Model Support

MFLUX supports compatible third-party models from HuggingFace that follow the FLUX architecture. The --model parameter accepts:

• Predefined names: dev, schnell, fibo, z-image-turbo, etc.
• HuggingFace repos: Freepik/flux.1-lite-8B, briaai/Fibo-mlx-4bit
• Local paths: /Users/me/models/my-model, ~/my-model

This unified interface mirrors how LoRA paths work, making it easy to switch between local and remote models.

# Using a HuggingFace repo
mflux-generate \
    --model Freepik/flux.1-lite-8B \
    --base-model schnell \
    --steps 4 \
    --seed 42 \
    --prompt "A beautiful landscape with mountains and a lake"

# Using a local path
mflux-generate \
    --model /Users/me/models/flux-lite \
    --base-model schnell \
    --steps 4 \
    --seed 42 \
    --prompt "A beautiful landscape with mountains and a lake"

Some examples of compatible third-party models include:

• Freepik/flux.1-lite-8B-alpha - A lighter version of FLUX
• shuttleai/shuttle-3-diffusion - Shuttle's implementation based on FLUX

The model will be automatically downloaded from HuggingFace the first time you use it, similar to the official FLUX models.

Note: Third-party models may have different performance characteristics, capabilities, or limitations compared to the official FLUX models. Always refer to the model's documentation on HuggingFace for specific usage instructions.

🎨 Image-to-Image

One way to condition the image generation is by starting from an existing image and let MFLUX produce new variations. Use the --image-path flag to specify the reference image, and the --image-strength to control how much the reference image should guide the generation. For example, given the reference image below, the following command produced the first image using the Sketching LoRA:

mflux-generate \
--prompt "sketching of an Eiffel architecture, masterpiece, best quality. The site is lit by lighting professionals, creating a subtle illumination effect. Ink on paper with very fine touches with colored markers, (shadings:1.1), loose lines, Schematic, Conceptual, Abstract, Gestural. Quick sketches to explore ideas and concepts." \
--image-path "reference.png" \
--image-strength 0.3 \
--lora-paths Architectural_Sketching.safetensors \
--lora-scales 1.0 \
--model dev \
--steps 20 \
--seed 43 \
--guidance 4.0 \
--quantize 8 \
--height 1024 \
--width 1024

Like with Controlnet, this technique combines well with LoRA adapters:

In the examples above the following LoRAs are used Sketching, Animation Shot and flux-film-camera are used.

🦙 Qwen Models

MFLUX supports the Qwen Image family of vision-language models, providing both text-to-image generation and natural language image editing capabilities. Released approximately a year after FLUX, Qwen models achieve state-of-the-art performance in most areas, though they are comparatively heavier to run.

🖼️ Qwen Image

Qwen Image is a powerful 20B parameter text-to-image model (technical report) that enables high-quality image generation from text prompts. It uses a vision-language architecture with a 7B text encoder (Qwen2.5-VL) to understand and generate images based on natural language descriptions.

The Qwen Image model has its own dedicated command mflux-generate-qwen. Qwen Image excels at multilingual prompts, including Chinese characters, and can render Chinese text as part of the image content (like signs, menus, and calligraphy).

Example: Wildlife Portrait

mflux-generate-qwen \
  --prompt "Close-up portrait of a majestic tiger in its natural habitat, detailed fur texture, piercing eyes, natural forest background, soft natural lighting, wildlife photography, photorealistic, high detail, professional wildlife shot" \
  --negative-prompt "blurry, low quality, distorted, deformed, ugly, bad anatomy, bad proportions, extra limbs, duplicate, watermark, signature, text, letters, cartoon, anime, painting, drawing, illustration, 3d render, cgi, zoo, cage, artificial" \
  --width 1920 \
  --height 816 \
  --steps 30 \
  --seed 42 \
  -q 8

mflux-generate-qwen \
  --prompt "Traditional Chinese calligraphy studio, ancient scrolls with beautiful Chinese characters, ink brushes, inkstone, traditional paper, warm natural lighting, peaceful atmosphere, photorealistic, high detail, cultural heritage" \
  --negative-prompt "blurry, low quality, distorted, deformed, ugly, bad anatomy, bad proportions, extra limbs, duplicate, watermark, signature, text, letters, cartoon, anime, painting, drawing, illustration, 3d render, cgi, modern, digital" \
  --width 1920 \
  --height 816 \
  --steps 30 \
  --seed 42 \
  -q 8

mflux-generate-qwen \
  --prompt "Traditional Chinese street scene, old neighborhood with shop signs displaying Chinese characters (店铺, 餐厅, 书店), red lanterns, narrow alleys, traditional architecture, bustling street life, natural lighting, photorealistic, high detail, street photography" \
  --negative-prompt "blurry, low quality, distorted, deformed, ugly, bad anatomy, bad proportions, extra limbs, duplicate, watermark, signature, cartoon, anime, painting, drawing, illustration, 3d render, cgi, modern signs, English text only" \
  --width 1920 \
  --height 816 \
  --steps 30 \
  --seed 42 \
  -q 8

mflux-generate-qwen \
  --prompt "Professional food photography, gourmet Chinese cuisine, steamed dumplings, colorful vegetables, traditional table setting, restaurant lighting, shallow depth of field, photorealistic, high detail, magazine quality" \
  --negative-prompt "blurry, low quality, distorted, deformed, ugly, bad anatomy, bad proportions, extra limbs, duplicate, watermark, signature, text, letters, cartoon, anime, painting, drawing, illustration, 3d render, cgi, fast food, unappetizing" \
  --width 1920 \
  --height 816 \
  --steps 30 \
  --seed 42 \
  -q 8

⚠️ Note: The Qwen Image model requires downloading the Qwen/Qwen-Image model weights (~58GB for the full model, or use quantization for smaller sizes).

✏️ Qwen Image Edit

Qwen Image Edit enables precise natural language image editing, allowing you to modify images using text instructions while maintaining their original structure and context. The model uses a vision-language encoder to understand both the input image and your editing instructions, making it ideal for tasks like changing specific elements, adjusting poses, modifying clothing, or altering backgrounds while preserving the overall composition.

Qwen Image Edit supports natural language editing with descriptive text instructions, maintains original poses and body positions when requested, supports multiple images for complex compositions, and works seamlessly with LoRA adapters for specialized transformations like camera angles and styles. The model uses Qwen/Qwen-Image-Edit-2509.

Examples showing dog replacement with two-image input and monkey camera angle transformations with LoRAs. Source images: Golden Retriever, Grey Dog, and Monkey.

Example 1: Two-Image Transformation (Dog Replacement)

Qwen Image Edit excels at complex transformations using multiple reference images. This example replaces a golden retriever with a grey dog and changes the rose color from white to red:

mflux-generate-qwen-edit \
  --image-paths "dog1.png" "dog2.png" \
  --prompt "Replace the golden retriever (standing outside, holding white rose) in Image 1 with the grey dog from Image 2 (which is standing inside in a studio). The grey dog should hold a red rose in its mouth and stand outside in the same position as the golden retriever. Maintain the outside environment, background, lighting, and all surroundings completely unchanged." \
  --steps 30 \
  --guidance 2.5 \
  --width 624 \
  --height 1024

Example 2: Single Image with LoRAs (Camera Angle Transformations)

Qwen Image Edit works seamlessly with LoRA adapters for specialized transformations. This example uses two LoRAs to transform camera angles on a single image:

mflux-generate-qwen-edit \
  --image-paths "monkey.png" \
  --prompt "将镜头极度拉近，使用超长焦镜头进行极端特写拍摄，主体占据画面的大部分空间，背景完全虚化，营造出强烈的视觉冲击力和亲密感。Extreme zoom in with a super telephoto lens, creating an intense close-up where the subject dominates most of the frame, with the background completely blurred, creating a strong visual impact and sense of intimacy." \
  --steps 8 \
  --guidance 2.5 \
  --width 1024 \
  --height 1024 \
  --lora-paths "lightx2v/Qwen-Image-Lightning" "dx8152/Qwen-Edit-2509-Multiple-angles" \
  --lora-scales 0.5 1.0

Uses Qwen Image Lightning LoRA for fast generation and Camera Angle LoRA for precise camera control.

Tips for Qwen Image Edit:

1. Detailed Prompts: The model works best with detailed, specific editing instructions
2. Pose Maintenance: Explicitly mention maintaining poses, body positions, or overall stance when you want to preserve the original structure
3. Single Focus: Focus on one or a few related edits at a time for more predictable results
4. LoRA Combinations: Combine multiple LoRAs for complex effects (e.g., fast generation + camera control)
5. Quantization: 6-bit or below can degrade the image a lot more compared to Flux, use with caution
6. Seed Variation: Qwen models typically do not vary much with seed changes. If you want more variation, vary the prompt instead
7. Image Quality: Qwen images come out quite soft compared to Flux models

⚠️ Note: The Qwen Image Edit model requires downloading the Qwen/Qwen-Image-Edit-2509 model weights (~58GB for the full model, or use quantization for smaller sizes).

🌀 FIBO

MFLUX supports FIBO from Bria.ai, the first open-source JSON-native text-to-image model trained on long structured captions. FIBO delivers high image quality, strong prompt adherence, and professional-grade control—trained exclusively on licensed data. (Technical Paper)

FIBO is an 8B-parameter DiT-based, flow-matching model using SmolLM3-3B as the text encoder with a novel DimFusion conditioning architecture for efficient long-caption training, and Wan 2.2 as the VAE. The VLM-assisted prompting uses a fine-tuned Qwen3-VL to expand short user intents, fill in missing details, and extract/edit structured prompts from images.

Most text-to-image models excel at imagination—but not control. FIBO is trained on structured JSON captions up to 1,000+ words, enabling precise, reproducible control over lighting, composition, color, and camera settings. The structured captions foster native disentanglement, allowing targeted, iterative refinement without prompt drift.

Key Features

• VLM-guided JSON-native prompting: Transform short prompts into structured schemas with 1,000+ words (lighting, camera, composition, DoF)
• Disentangled control: Tweak a single attribute (e.g., camera angle) without breaking the scene
• Strong prompt adherence: High alignment on PRISM-style evaluations
• Enterprise-grade: 100% licensed data with governance, repeatability, and legal clarity

The three modes: ✨ Generate, 🔧 Refine, and 💡 Inspire

✨ Generate: While the actual prompt input to FIBO is a structured JSON file, the generate command provides an interface to input pure text prompts. These are then expanded into structured JSON prompts using FIBO's Vision-Language Model (VLM) before being passed to the diffusion model for image generation. For example, the following prompt produces one of the images above:

mflux-generate-fibo \
  --prompt "Three cartoon animal chefs in a colorful bakery kitchen, Pixar style: a bunny with floppy ears wearing a tall white chef hat and pink apron holding a chocolate cake on the left, a raccoon with a striped tail wearing blue oven mitts and a yellow bandana frosting cupcakes in the center, a penguin wearing a red bowtie and checkered apron carrying a tray of golden croissants on the right, warm kitchen lighting with flour dust in air" \
  --width 1200 \
  --height 540 \
  --steps 20 \
  --guidance 4.0 \
  --seed 42 \
  --output animal_bakers.png

This command will output both the generated image (animal_bakers.png) and a JSON prompt file (animal_bakers.json) containing the expanded structured prompt used for generation. When the input prompt is pure text, it will be processed through FIBO's VLM to create the structured JSON prompt automatically. Conversely, if a JSON prompt file is provided, it will be used directly for image generation, thus bypassing the VLM step and giving you full control over the prompt structure. Another way to call the model directly is to provide a JSON prompt file as input:

mflux-generate-fibo \
    --prompt-file animal_bakers.json \
    --width 1200 \
    --height 540 \
    --steps 20 \
    --guidance 4.0 \
    --seed 42 \
    --output animal_bakers.png

A point worth emphasizing is that when working with a JSON prompt file, the user can use whatever tool they prefer to edit it and is not forced to use the built in FIBO-VLM. Other good alternatives are coding agents, other LLMs/VLMs etc.

{
  "short_description": "Three cartoon animal chefs are in a bakery kitchen, each holding a culinary creation. A bunny chef on the left presents a chocolate cake, a raccoon chef in the center is frosting cupcakes, and a penguin chef on the right carries a tray of croissants. The kitchen is brightly lit with warm tones, and flour dusts the air, creating a lively and cheerful baking atmosphere.",
  "objects": [
    {
      "description": "A cartoon bunny wearing a white chef's hat and a pink apron, holding a chocolate cake with white frosting and cherries.",
      "location": "left foreground",
      "relationship": "The bunny chef is presenting the chocolate cake.",
      "relative_size": "medium",
      "shape_and_color": "Rounded bunny shape, white hat, pink apron, brown cake, white frosting, red cherries.",
      "texture": "smooth",
      "appearance_details": "Floppy ears, rosy cheeks, smiling expression.",
      "pose": "Standing upright, holding the cake with both hands.",
      "expression": "Joyful and proud.",
      "clothing": "White chef's hat, pink apron.",
      "action": "Holding and presenting a cake.",
      "gender": "female",
      "skin_tone_and_texture": "White fur, smooth texture.",
      "orientation": "Upright, facing forward."
    },
    {
      "description": "A cartoon raccoon wearing blue oven mitts and a yellow bandana, actively frosting cupcakes with pink and yellow frosting.",
      "location": "center midground",
      "relationship": "The raccoon chef is in the process of frosting cupcakes.",
      "relative_size": "medium",
      "shape_and_color": "Distinct raccoon shape, blue mitts, yellow bandana, pink and yellow frosting, brown cupcakes.",
      "texture": "smooth",
      "appearance_details": "Striped tail, bushy fur, focused expression.",
      "pose": "Leaning forward slightly, hands busy frosting.",
      "expression": "Concentrated and happy.",
      "clothing": "Blue oven mitts, yellow bandana.",
      "action": "Frosting cupcakes.",
      "gender": "male",
      "skin_tone_and_texture": "Brown and black fur, smooth texture.",
      "orientation": "Upright, slightly angled."
    },
    {
      "description": "A cartoon penguin wearing a red bowtie and a checkered apron, carrying a tray of golden croissants.",
      "location": "right foreground",
      "relationship": "The penguin chef is carrying a tray of freshly baked croissants.",
      "relative_size": "medium",
      "shape_and_color": "Classic penguin shape, red bowtie, red and white apron, golden croissants.",
      "texture": "smooth",
      "appearance_details": "Black and white body, orange beak and feet, smiling expression.",
      "pose": "Standing upright, holding the tray with both hands.",
      "expression": "Cheerful and friendly.",
      "clothing": "Red bowtie, checkered apron.",
      "action": "Carrying a tray of croissants.",
      "gender": "male",
      "skin_tone_and_texture": "Feathered texture, smooth appearance.",
      "orientation": "Upright, facing forward."
    },
    {
      "description": "A chocolate cake with white frosting and two red cherries on top.",
      "location": "left foreground",
      "relationship": "Held by the bunny chef.",
      "relative_size": "medium",
      "shape_and_color": "Round cake, dark brown, white frosting, red cherries.",
      "texture": "smooth frosting, slightly textured cake",
      "appearance_details": "Decorated with cherries.",
      "number_of_objects": 1,
      "orientation": "Horizontal"
    },
    {
      "description": "A tray filled with golden-brown croissants.",
      "location": "right foreground",
      "relationship": "Carried by the penguin chef.",
      "relative_size": "medium",
      "shape_and_color": "Elongated, crescent-shaped croissants, golden brown.",
      "texture": "flaky, slightly crisp exterior",
      "appearance_details": "Arranged neatly on a metal tray.",
      "number_of_objects": 1,
      "orientation": "Horizontal"
    }
  ],
  "background_setting": "A brightly lit bakery kitchen with wooden countertops, shelves stocked with baking ingredients and equipment, and a window in the background. Flour is lightly dusted in the air.",
  "lighting": {
    "conditions": "warm indoor lighting",
    "direction": "front-lit and side-lit",
    "shadows": "soft, diffused shadows"
  },
  "aesthetics": {
    "composition": "centered composition with the three chefs forming a horizontal line",
    "color_scheme": "warm and cheerful, with dominant browns, yellows, pinks, and whites",
    "mood_atmosphere": "joyful, friendly, and inviting",
    "aesthetic_score": "very high",
    "preference_score": "very high"
  },
  "photographic_characteristics": {
    "depth_of_field": "shallow",
    "focus": "sharp focus on the chefs and their creations",
    "camera_angle": "eye-level",
    "lens_focal_length": "standard lens"
  },
  "style_medium": "digital illustration",
  "text_render": [],
  "context": "This image is a charming illustration, likely for a children's book, educational material, or a bakery-themed advertisement, designed to evoke feelings of happiness and the joy of baking.",
  "artistic_style": "Pixar-style animation"
}

🔧 Refine: While the JSON prompt can be edited manually, it can be quite complex and inconvenient to modify directly. The refinement mode helps to solve this issue by also expanding a simple user instruction in order to tweak specific attributes. The VLM processes these instructions and updates the JSON prompt accordingly before generating new images.

Assuming we already have a previous prompt file, like owl_brown.json, we can refine this prompt to change the owl's color and add some accessories:

mflux-refine-fibo \
    --prompt-file owl_brown.json \
    --instructions "Make the owl white instead of brown, and add round glasses and a black scarf. Keep everything else exactly the same - the same forest background, moonlight lighting, composition, and overall whimsical atmosphere." \
    --output owl_white.json

{
  "short_description": "A hyper-detailed, ultra-fluffy owl sitting in the trees at night, looking directly at the camera with wide, adorable, expressive eyes. Its feathers are soft and voluminous, catching the cool moonlight with subtle silver highlights. The owl's gaze is curious and full of charm, giving it a whimsical, storybook-like personality. It is wearing round glasses and a black scarf.",
  "objects": [
    {
      "description": "An adorable, fluffy owl with large, expressive eyes and soft, voluminous feathers. Its plumage is white, with subtle silver highlights from the moonlight. It is wearing round glasses and a black scarf.",
      "location": "center",
      "relationship": "The owl is the sole subject, perched comfortably within its environment.",
      "relative_size": "large within frame",
      "shape_and_color": "Round head, large eyes, bulky body, predominantly white with silver accents.",
      "texture": "Extremely soft, fluffy, and detailed feathers, giving a plush toy-like appearance.",
      "appearance_details": "The eyes are wide, dark, and reflective, conveying a sense of wonder and curiosity. The beak is small and light-colored, almost hidden by the feathers. Subtle silver highlights catch the moonlight on its feathers. It has round glasses on its nose and a black scarf around its neck.",
      "orientation": "upright, facing forward"
    }
  ],
  "background_setting": "A dark, nocturnal forest setting with blurred trees and foliage, illuminated by a soft, cool moonlight. The background is out of focus, emphasizing the owl.",
  "lighting": {
    "conditions": "moonlight",
    "direction": "backlit and side-lit from the left",
    "shadows": "soft, diffused shadows on the right side of the owl and within the background foliage, indicating a single light source."
  },
  "aesthetics": {
    "composition": "centered, portrait composition",
    "color_scheme": "cool blues and silvers from the moonlight contrasting with white of the owl and forest.",
    "mood_atmosphere": "mysterious, enchanting, whimsical, and serene.",
    "aesthetic_score": "very high",
    "preference_score": "very high"
  },
  "photographic_characteristics": {
    "depth_of_field": "shallow",
    "focus": "sharp focus on the owl's face and eyes, with a soft blur in the background.",
    "camera_angle": "eye-level",
    "lens_focal_length": "portrait lens (e.g., 50mm-85mm)"
  },
  "style_medium": "digital illustration",
  "text_render": [],
  "context": "A whimsical character illustration, possibly for a children's book, animated film, or fantasy art collection.",
  "artistic_style": "fantasy, illustrative, detailed"
}

Finally, generate the refined white owl image using the updated JSON prompt:

mflux-generate-fibo \
    --prompt-file owl_white.json \
    --width 1024 \
    --height 560 \
    --steps 20 \
    --guidance 4.0 \
    --seed 42 \
    --quantize 4 \
    --output owl_white.png

The refine command reads the existing JSON prompt, applies the refinement instructions to change the owl's color and add accessories, and outputs a new refined JSON file. This refined prompt is then used to generate a new image that reflects the requested changes while maintaining the overall scene and composition.

It is worth noting that refine does not work the same way as other editing techniques like Flux Kontext or Qwen Image Edit. Instead of modifying an existing image, it modifies the underlying structured prompt to produce a new image that reflects the requested changes while maintaining the overall scene and composition.

💡 Inspire: Provide an image instead of text. FIBO's vision-language model extracts a detailed, structured prompt, blends it with your creative intent, and produces related images—ideal for inspiration without overreliance on the original.

Starting from an image, you can extract a structured JSON prompt that captures its visual characteristics. For example, using a blue and brown bird on brown tree trunk, we can extract a detailed prompt:

mflux-inspire-fibo \
    --image-path bird.jpg \
    --prompt "blue and brown bird on brown tree trunk" \
    --output bird_inspired.json \
    --seed 42

This command analyzes the image and generates a structured JSON prompt file (bird_inspired.json) that describes the visual elements, composition, lighting, and style. You can then use this JSON prompt to generate new images with similar characteristics:

mflux-generate-fibo \
    --prompt-file bird_inspired.json \
    --width 1024 \
    --height 672 \
    --steps 20 \
    --guidance 4.0 \
    --seed 42 \
    -q 8 \
    --output bird_inspired.png

{
  "short_description": "A vibrant blue and brown kingfisher is perched on a weathered tree trunk, facing left. The bird's iridescent plumage is detailed, with striking orange and white markings on its chest and throat. Its long, sharp black beak is prominent. The background is a soft, out-of-focus gradient of warm yellow and green, creating a natural and serene environment. The lighting highlights the textures of the bird's feathers and the rough bark of the trunk.",
  "objects": [
    {
      "description": "A male kingfisher with striking iridescent blue plumage on its back and wings, a rich orange and white chest, and a black beak. It has a small, dark eye and a red-orange patch on its face.",
      "location": "center",
      "relationship": "perched on the tree trunk",
      "relative_size": "medium within frame",
      "shape_and_color": "Bird shape, predominantly blue, orange, and white.",
      "texture": "Feathers appear smooth and slightly glossy.",
      "appearance_details": "The beak is long, thin, and black. The orange patch on its face is distinct.",
      "number_of_objects": 1,
      "pose": "Standing upright on its legs, head turned to the left.",
      "expression": "Alert and focused.",
      "action": "Perched, observing its surroundings.",
      "gender": "male",
      "orientation": "Facing left, upright"
    },
    {
      "description": "A section of a weathered, rough tree trunk, providing a perch for the kingfisher. It has a natural, organic shape with visible bark texture.",
      "location": "bottom-center foreground",
      "relationship": "supports the kingfisher",
      "relative_size": "medium",
      "shape_and_color": "Irregular cylindrical shape, brown and grey tones.",
      "texture": "Rough, gnarled bark texture.",
      "appearance_details": "Some smaller branches or knots are visible on the trunk.",
      "number_of_objects": 1,
      "orientation": "Horizontal, lying on its side"
    }
  ],
  "background_setting": "A soft, blurred background with a warm gradient transitioning from a light yellow at the top to a muted green at the bottom. This creates a natural, out-of-focus environment, likely foliage or sky.",
  "lighting": {
    "conditions": "natural daylight",
    "direction": "side-lit from the right",
    "shadows": "soft shadows, particularly on the left side of the bird and the trunk"
  },
  "aesthetics": {
    "composition": "rule of thirds, with the bird positioned slightly off-center",
    "color_scheme": "vibrant blues and oranges contrasting with the soft yellow and green background",
    "mood_atmosphere": "serene, natural, captivating",
    "aesthetic_score": "very high",
    "preference_score": "very high"
  },
  "photographic_characteristics": {
    "depth_of_field": "shallow, with a strong bokeh effect in the background",
    "focus": "sharp focus on the kingfisher",
    "camera_angle": "eye-level",
    "lens_focal_length": "telephoto lens"
  },
  "style_medium": "photograph",
  "text_render": [],
  "context": "This image is a wildlife photograph, likely intended for nature magazines, educational materials, or as a decorative print for nature enthusiasts.",
  "artistic_style": "photorealistic, detailed"
}

The inspire command is particularly useful when you want to:

• Extract the visual style and composition from a reference image
• Create variations of an existing image while maintaining its core characteristics
• Understand how FIBO interprets and structures visual information
• Blend your creative intent (via the optional --prompt parameter) with the visual content of the image

Note: The optional --prompt parameter allows you to guide the VLM's interpretation of the image. For example, you might use --prompt "futuristic cityscape" to influence how the image is analyzed and structured.

⚠️ Note: FIBO requires downloading the briaai/FIBO model weights (~24GB) and the briaai/FIBO-vlm vision-language model (~8GB), totaling ~32GB for the full model, or use quantization for smaller sizes.

⚡ Z-Image

MFLUX supports Z-Image-Turbo from Tongyi Lab (Alibaba), released in November 2025. Z-Image is an efficient 6B-parameter image generation model with a single-stream DiT architecture. Z-Image-Turbo delivers high-quality images in just 9 steps, making it one of the fastest open-source models available. All the standard modes such as, img2img, LoRA and quantizations are supported for this model. See the technical paper for more details.

Example

The following uses the pre-quantized 4-bit model from filipstrand/Z-Image-Turbo-mflux-4bit to generate a vibrant 1960s style image with a LoRA adapter Technically Color for enhanced film color:

mflux-generate-z-image-turbo \
  --model filipstrand/Z-Image-Turbo-mflux-4bit \
  --prompt "t3chnic4lly vibrant 1960s close-up of a woman sitting under a tree in a blue skirt and white blouse, she has blonde wavy short hair and a smile with green eyes lake scene by a garden with flowers in the foreground 1960s style film She's holding her hand out there is a small smooth frog in her palm, she's making eye contact with the toad." \
  --width 1280 \
  --height 720 \
  --seed 456 \
  --steps 9 \
  --lora-paths renderartist/Technically-Color-Z-Image-Turbo \
  --lora-scales 0.5

⚠️ Note: Z-Image-Turbo requires downloading the Tongyi-MAI/Z-Image-Turbo model weights (~31GB), or use quantization for smaller sizes.

Dreambooth fine-tuning for Z-Image is not yet supported in MFLUX but is planned. In the meantime, you can train Z-Image-Turbo LoRAs using AI Toolkit - see How to Train a Z-Image-Turbo LoRA with AI Toolkit by Ostris AI.

For a Swift MLX implementation of Z-Image, see zimage.swift by @mzbac.

🔌 LoRA

MFLUX support loading trained LoRA adapters (actual training support is coming).

The following example The_Hound LoRA from @TheLastBen:

mflux-generate --prompt "sandor clegane" --model dev --steps 20 --seed 43 -q 8 --lora-paths "sandor_clegane_single_layer.safetensors"

The following example is Flux_1_Dev_LoRA_Paper-Cutout-Style LoRA from @Norod78:

mflux-generate --prompt "pikachu, Paper Cutout Style" --model schnell --steps 4 --seed 43 -q 8 --lora-paths "Flux_1_Dev_LoRA_Paper-Cutout-Style.safetensors"

Note that LoRA trained weights are typically trained with a trigger word or phrase. For example, in the latter case, the sentence should include the phrase "Paper Cutout Style".

Also note that the same LoRA weights can work well with both the schnell and dev models. Qwen models support LoRA but may require Qwen-specific LoRA weights. Refer to the original LoRA repository to see what mode it was trained for.

Multi-LoRA

Multiple LoRAs can be sent in to combine the effects of the individual adapters. The following example combines both of the above LoRAs:

mflux-generate \
   --prompt "sandor clegane in a forest, Paper Cutout Style" \
   --model dev \
   --steps 20 \
   --seed 43 \
   --lora-paths sandor_clegane_single_layer.safetensors Flux_1_Dev_LoRA_Paper-Cutout-Style.safetensors \
   --lora-scales 1.0 1.0 \
   -q 8

Just to see the difference, this image displays the four cases: One of having both adapters fully active, partially active and no LoRA at all. The example above also show the usage of --lora-scales flag.

HuggingFace LoRA Downloads

MFLUX can automatically download LoRAs directly from HuggingFace. Simply pass the repository ID to --lora-paths:

# Download from a HuggingFace repo (auto-finds the .safetensors file)
mflux-generate \
    --prompt "a portrait" \
    --lora-paths "author/lora-model"

For repositories with multiple LoRA files (collections), use the repo_id:filename format to specify which file to download:

# Download a specific file from a collection
mflux-generate \
    --prompt "film storyboard style, a cat" \
    --lora-paths "ali-vilab/In-Context-LoRA:film-storyboard.safetensors"

Downloaded LoRAs are cached locally and reused on subsequent runs.

LoRA Library Path

MFLUX supports a convenient LoRA library feature that allows you to reference LoRA files by their basename instead of full paths. This is particularly useful when you have a collection of LoRA files organized in one or more directories.

To use this feature, set the LORA_LIBRARY_PATH environment variable to point to your LoRA directories. You can specify multiple directories separated by colons (:):

export LORA_LIBRARY_PATH="/path/to/loras:/another/path/to/more/loras"

Once set, MFLUX will automatically discover all .safetensors files in these directories (including subdirectories) and allow you to reference them by their basename:

# Instead of using full paths:
mflux-generate \
    --prompt "a portrait" \
    --lora-paths "/path/to/loras/style1.safetensors" "/another/path/to/more/loras/style2.safetensors"

# You can simply use basenames:
mflux-generate \
    --prompt "a portrait" \
    --lora-paths "style1" "style2"

Supported LoRA formats (updated)

Since different fine-tuning services can use different implementations of FLUX, the corresponding LoRA weights trained on these services can be different from one another. The aim of MFLUX is to support the most common ones. The following table show the current supported formats:

To report additional formats, examples or other any suggestions related to LoRA format support, please see issue #47.

🎭 In-Context Generation

In-Context Generation is a powerful collection of techniques that allows you to generate images based on reference images and context, without requiring model fine-tuning. MFLUX supports multiple in-context approaches, each designed for specific use cases ranging from style transfer to virtual try-on and image editing.

📸 Kontext

FLUX.1 Kontext, released in June 2025, is Black Forest Labs' official model that goes beyond text-to-image generation. Unlike previous flow models that only allow text-based generation, Kontext understands and creates from existing images, enabling flexible image editing through simple text instructions without complex workflows or finetuning. Out of the various in-context generation techniques, Kontext is the most advanced and versatile, allowing for a wide range of image editing and generation tasks. It is recommended to try Kontext first before exploring other in-context methods.

Original images credit: Jon Tyson (sign), Daniel Seßler (town), Liga Alksne (house) on Unsplash

Kontext's core capabilities include character consistency (preserving unique elements across scenes), local editing (targeted modifications without affecting the rest), style reference (generating novel scenes while preserving styles), and interactive speed for iterative refinement with minimal latency.

Example Usage with sequential edits

The image above illustrates sequential editing with Kontext - making multiple individual edits to progressively refine an image. Each edit builds upon the previous result, allowing for precise, iterative modifications.

Here's an example of one step in a sequential editing workflow, where we add atmospheric mist to the mountains:

mflux-generate-kontext \
  --image-path "house_without_background_objects.png" \
  --prompt "Make the mountains in the background be covered in white mist so that they are barely visible. Preserve the original camera angle, house placement etc" \
  --steps 20 \
  --seed 9375333 \
  --guidance 2.5 \
  --width 912 \
  --height 1360 \
  -q 8

Tips for Best Results

For comprehensive prompting strategies, see the official Black Forest Labs Kontext prompting guide.

Core Principles:

• Be Specific and Clear: Use precise descriptions, avoid vague terms
• Step-by-step Editing: Break complex modifications into multiple simple steps
• Explicit Preservation: State what should remain unchanged
• Verb Selection: Use "change", "replace" rather than "transform"

Prompting Techniques:

Basic Modifications:

• Simple: "Change the car color to red"
• Maintain style: "Change to daytime while maintaining the same style of the painting"

Character Consistency:

• Use specific descriptions: "The woman with short black hair" instead of "she"
• Preserve features: "while maintaining the same facial features, hairstyle, and expression"

Style Transfer:

• Name the style: "Transform to Bauhaus art style"
• Describe characteristics: "Transform to oil painting with visible brushstrokes, thick paint texture"
• Preserve composition: "Change to Bauhaus style while maintaining the original composition"

Text Editing:

• Use quotes: "Replace 'joy' with 'BFL'"
• Maintain format: "Replace text while maintaining the same font style"

Common Problems & Solutions:

❌ Character changes too much: "Transform the person into a Viking"
✅ Better: "Change the clothes to be a viking warrior while preserving facial features"

❌ Position changes: "Put him on a beach"
✅ Better: "Change the background to a beach while keeping the person in the exact same position, scale, and pose"

❌ Vague style: "Make it a sketch"
✅ Better: "Convert to pencil sketch with natural graphite lines, cross-hatching, and visible paper texture"

Ready-to-Use Templates:

• Object Modification: "Change [object] to [new state], keep [content to preserve] unchanged"
• Style Transfer: "Transform to [specific style], while maintaining [composition/character/other] unchanged"
• Background Replacement: "Change the background to [new background], keep the subject in the exact same position and pose"
• Text Editing: "Replace '[original text]' with '[new text]', maintain the same font style"

Technical Tips:

1. High-Quality References: Use clear, well-lit reference images with distinct characteristics
2. Guidance Scale: Experiment with guidance values between 2.5-4.0 for optimal balance
3. Multiple Seeds: Try different seeds to explore variations while maintaining consistency
4. Resolution: Use standard resolutions (1024x1024, 768x1024, etc.) for best results

⚠️ Note: Using the Kontext tool requires an additional ~34 GB download from black-forest-labs/FLUX.1-Kontext-dev. The download happens automatically on first use.

🎨 In-Context LoRA

In-Context LoRA allows you to generate images in a specific style based on a reference image. This approach uses specialized LoRA weights that enable the model to understand and apply the visual context from your reference image to a new generation.

This feature is based on the In-Context LoRA for Diffusion Transformers project by Ali-ViLab.

To use In-Context LoRA, you need:

1. A reference image
2. A style LoRA (optional - the in-context ability works without LoRAs, but they can significantly enhance the results)

Available Styles

MFLUX provides several pre-defined styles from the Hugging Face ali-vilab/In-Context-LoRA repository that you can use with the --lora-style argument:

How It Works

The In-Context LoRA generation creates a side-by-side image where:

• The left side shows your reference image with noise applied
• The right side shows the new generation that follows your prompt while maintaining the visual context

The final output is automatically cropped to show only the right half (the generated image).

Prompting for In-Context LoRA

For best results with In-Context LoRA, your prompt should describe both the reference image and the target image you want to generate. Use markers like [IMAGE1], [LEFT], or [RIGHT] to distinguish between the two parts.

Here's an example:

mflux-generate-in-context \
  --model dev \
  --steps 20 \
  --quantize 8 \
  --seed 42 \
  --height 1024 \
  --width 1024 \
  --image-path "reference.png" \
  --lora-style identity \
  --prompt "In this set of two images, a bold modern typeface with the brand name 'DEMA' is introduced and is shown on a company merchandise product photo; [IMAGE1] a simplistic black logo featuring a modern typeface with the brand name 'DEMA' on a bright light green/yellowish background; [IMAGE2] the design is printed on a green/yellowish hoodie as a company merchandise product photo with a plain white background."

This prompt clearly describes both the reference image (after [IMAGE1]) and the desired output (after [IMAGE2]). Other marker pairs you can use include:

• [LEFT] and [RIGHT]
• [TOP] and [BOTTOM]
• [REFERENCE] and [OUTPUT]

Important: In the current implementation, the reference image is ALWAYS placed on the left side of the composition, and the generated image on the right side. When using marker pairs in your prompt, the first marker (e.g., [IMAGE1], [LEFT], [REFERENCE]) always refers to your reference image, while the second marker (e.g., [IMAGE2], [RIGHT], [OUTPUT]) refers to what you want to generate.

Tips for Best Results

1. Choose the right reference image: Select a reference image with a clear composition and structure that matches your intended output.
2. Adjust guidance: Higher guidance values (7.0-9.0) tend to produce results that more closely follow your prompt.
3. Try different styles: Each style produces distinctly different results - experiment to find the one that best matches your vision.
4. Increase steps: For higher quality results, use 25-30 steps.
5. Detailed prompting: Be specific about both the reference image and your desired output in your prompt.
6. Try without LoRA: While LoRAs enhance the results, you can experiment without them to see the base in-context capabilities.

👕 CatVTON (Virtual Try-On)

⚠️ Experimental Feature: CatVTON is an experimental feature and may be removed or significantly changed in future updates.

CatVTON enables virtual try-on capabilities using in-context learning. This approach allows you to generate images of people wearing different garments by providing a person image, a person mask, and a garment image.

The implementation is based on @nftblackmagic/catvton-flux and uses the model weights from xiaozaa/catvton-flux-beta (approximately 24 GB download).

How it works

CatVTON uses a sophisticated in-context learning approach that creates a side-by-side composition for virtual try-on:

1. Image Layout: The garment image is placed on the left side, while the person image is positioned on the right side of the composition.

2. Selective Processing: The model treats each side differently:

   • Left side (garment): The model can only read information from this area - no inpainting or modifications occur here. This serves as a reference for the garment's appearance, texture, and style.
   • Right side (person): Only the areas highlighted in the person mask are inpainted. The mask determines exactly which parts of the person image should be modified to "wear" the garment.

3. Contextual Understanding: By reading the garment characteristics from the left and selectively applying them to the masked regions on the right, the model creates a realistic virtual try-on that maintains proper lighting, shadows, and fabric behavior.

This approach allows the model to understand the garment's properties while precisely controlling which parts of the person image should be transformed, resulting in natural-looking virtual clothing fitting.

Example Command

mflux-generate-in-context-catvton \
  --person-image "person.png" \
  --person-mask "mask.png" \
  --garment-image "garment.png" \
  --prompt "The pair of images highlights a clothing and its styling on a model, high resolution, 4K, 8K; [IMAGE1] Detailed product shot of a light blue shirt with designer details such as white and pink patterns; [IMAGE2] The *exact* same cloth (the light blue shirt with designer details such as white and pink patterns) is worn by a model in a lifestyle setting." \
  --steps 20 \
  --seed 6269363 \
  --guidance 30 \
  --height 1024 \
  --width 891 \
  -q 8

Required Inputs

• Person Image: A photo of the person who will "wear" the garment
• Person Mask: A binary mask indicating the areas where the garment should be applied
• Garment Image: The clothing item to be virtually worn

CatVTON Features

• Automatic Prompting: If no prompt is provided, CatVTON uses an optimized default prompt designed for virtual try-on scenarios
• Side-by-Side Generation: Creates a diptych showing the garment product shot alongside the styled result
• Optimized for Clothing: Specifically tuned for clothing and fashion applications
• High-Quality Results: Maintains realistic lighting, shadows, and fabric properties

Tips for CatVTON

1. High-Quality Inputs: Use high-resolution, well-lit images for best results
2. Accurate Masks: Ensure the person mask precisely covers the areas where the garment should appear
3. Consistent Lighting: Match lighting conditions between person and garment images when possible
4. Garment Type: Works best with clearly defined clothing items (shirts, dresses, jackets, etc.)
5. Pattern Limitations: Very intricate patterns, fine details, and complex textures may not transfer well - simpler, solid colors and basic patterns typically work better
6. Try Multiple Seeds: Generate several variations with different seeds to find the best result, as outcomes can vary significantly

✏️ IC-Edit (In-Context Editing)

⚠️ Experimental Feature: IC-Edit is an experimental feature and may be removed or significantly changed in future updates.

IC-Edit provides intuitive image editing capabilities using natural language instructions. This approach automatically applies a specialized LoRA and generates edited versions of your reference image based on simple text instructions.

The implementation is based on @River-Zhang/ICEdit.

Original images credit: Jimmy Chang (flower), Kar Ming Moo (tiger), Martin Baron (car) on Unsplash

How it works

IC-Edit employs a streamlined diptych approach for natural language image editing:

1. Image Layout: The reference image is placed on the left side, while the right side is reserved for the edited result.

2. Automatic Masking: Unlike CatVTON, no user-provided mask is required. The system automatically creates a simple but effective mask:

   • Left side (reference): Completely black mask - no denoising occurs here, preserving the original image as reference
   • Right side (edit area): Completely white mask - the entire area is available for denoising and modification

3. Instruction Processing: Your natural language instruction is automatically wrapped in a diptych template that tells the model to create the desired changes on the right side while using the left side as reference.

4. Guided Generation: The model reads the visual information from the left side and applies the requested modifications to generate the edited result on the right side, maintaining visual coherence and context.

This simplified approach removes the complexity of mask creation while still providing precise control through natural language instructions, making image editing accessible and intuitive.

Example Command

mflux-generate-in-context-edit \
  --reference-image "flower.jpg" \
  --prompt "two images of the exact same flower in two different styles: On the left the photo has is in bright colors showing green leaves and a pink flower. On the right, the *exact* same photo (same flower, same leaves, same background, identical etc). but with where everything is black and white except for the flower which is still in color. The content is *exactly* the same between the left and right image, except only for the coloring (black and white for everything except for the colorful flower)" \
  --steps 20 \
  --seed 8570325 \
  --guidance 30 \
  -q 8

Key Features

• Natural Language Instructions: Use simple, descriptive instructions like "make the hair black", "add sunglasses", or "change the background to a beach"
• Automatic Prompting: Instructions are automatically wrapped in a diptych template for optimal results
• Optimal Resolution: Automatically resizes to 512px width (the resolution IC-Edit was trained on) while maintaining aspect ratio
• Specialized LoRA: Automatically downloads and applies the IC-Edit LoRA for enhanced editing capabilities

IC-Edit Options

You can use either --instruction for simple edits or --prompt for full control:

# Using instruction (recommended)
mflux-generate-in-context-edit \
  --reference-image "photo.jpg" \
  --instruction "remove the glasses"

# Using custom prompt (advanced)
mflux-generate-in-context-edit \
  --reference-image "photo.jpg" \
  --prompt "A diptych with two side-by-side images of the same scene. On the right, the scene is exactly the same as on the left but with a vintage filter applied"

Tips for IC-Edit

1. Clear Instructions: Use specific, actionable instructions for best results
2. Single Changes: Focus on one edit at a time for more predictable results
3. Reference Quality: Higher quality reference images generally produce better edits
4. Iterative Editing: Use the output of one edit as input for the next to build complex changes
5. Try Multiple Seeds: Generate several variations with different seeds to find the best result, as outcomes can vary significantly

⚠️ Note: Using the IC-Edit tool requires an additional ~230MB download for the specialized LoRA weights. The download happens automatically on first use. This remarkably small LoRA (less than 0.7% of the base model's ~34GB) enables sophisticated image editing capabilities, demonstrating that the base FLUX model is already highly competent at style transfers and transformations - the LoRA simply provides the user control and interface to access these latent capabilities.

🛠️ Flux Tools

MFLUX supports the official Flux.1 Tools.

🖌️ Fill

The Fill tool uses the FLUX.1-Fill-dev model to allow you to selectively edit parts of an image by providing a binary mask. This is useful for inpainting (replacing specific areas) and outpainting (expanding the canvas).

Inpainting

Inpainting allows you to selectively regenerate specific parts of an image while preserving the rest. This is perfect for removing unwanted objects, adding new elements, or changing specific areas of an image without affecting the surrounding content. The Fill tool understands the context of the entire image and creates seamless edits that blend naturally with the preserved areas.

Original dog image credit: Julio Bernal on Unsplash

Creating Masks

Before using the Fill tool, you need an image and a corresponding mask. You can create a mask using the included tool:

python -m tools.fill_mask_tool /path/to/your/image.jpg

This will open an interactive interface where you can paint over the areas you want to regenerate. Pressing the s key will save the mask at the same location as the image.

Example

To regenerate specific parts of an image:

mflux-generate-fill \
  --prompt "A professionally shot studio photograph of a dog wearing a red hat and ski goggles. The dog is centered against a uniformly bright yellow background, with well-balanced lighting and sharp details." \
  --steps 20 \
  --seed 42 \
  --height 1280 \
  --width 851 \
  --guidance 30 \
  -q 8 \
  --image-path "dog.png" \
  --masked-image-path "dog_mask.png" \

Outpainting

Original room image credit: Alexey Aladashvili on Unsplash

Outpainting extends your image beyond its original boundaries, allowing you to expand the canvas in any direction while maintaining visual consistency with the original content. This is useful for creating wider landscapes, revealing more of a scene, or transforming a portrait into a full-body image. The Fill tool intelligently generates new content that seamlessly connects with the existing image.

You can expand the canvas of your image using the provided tool:

python -m tools.create_outpaint_image_canvas_and_mask \
  /path/to/your/image.jpg \
  --image-outpaint-padding "0,30%,20%,0"

As an example, here's how to add 25% padding to both the left and right sides of an image:

python -m tools.create_outpaint_image_canvas_and_mask \
  room.png \
  --image-outpaint-padding "0,25%,0,25%"

The padding format is "top,right,bottom,left" where each value can be in pixels or as a percentage. For example, "0,30%,20%,0" expands the canvas by 30% to the right and 20% to the bottom.

After running this command, you'll get two files: an expanded canvas with your original image and a corresponding mask. You can then run the mflux-generate-fill command similar to the inpainting example, using these files as input.

Example

Once you've created the expanded canvas and mask files, run the Fill tool on them:

mflux-generate-fill \
  --prompt "A detailed interior room photograph with natural lighting, extended in a way that perfectly complements the original space. The expanded areas continue the architectural style, color scheme, and overall aesthetic of the room seamlessly." \
  --steps 25 \
  --seed 43 \
  --guidance 30 \
  -q 8 \
  --image-path "room.png" \
  --masked-image-path "room_mask.png" \

Tips for Best Results

• Model: The model is always FLUX.1-Fill-dev and should not be specified.
• Guidance: Higher guidance values (around 30) typically yield better results. This is the default if not specified.
• Resolution: Higher resolution images generally produce better results with the Fill tool.
• Masks: Make sure your mask clearly defines the areas you want to regenerate. White areas in the mask will be regenerated, while black areas will be preserved.
• Prompting: For best results, provide detailed prompts that describe both what you want in the newly generated areas and how it should relate to the preserved parts of the image.
• Steps: Using 20-30 denoising steps generally produces higher quality results.

⚠️ Note: Using the Fill tool requires an additional 33.92 GB download from black-forest-labs/FLUX.1-Fill-dev. The download happens automatically on first use.

🔍 Depth

Using the depth tool, you can generate high-quality images constrained on a depth map from a reference image. These maps represent the estimated distance of each pixel from the camera, with brighter areas representing objects closer to the camera and darker areas representing objects farther away.

For state-of-the-art depth extraction, MFLUX now supports the Depth Pro model, natively implemented in MLX based on the reference implementation.

Original hallway image credit: Yuliya Matuzava on Unsplash

Example

Using the mflux-generate-depth we can let MFLUX generate a new image conditioned on the depth map of the input image:

mflux-generate-depth \
  --prompt "A hallway made of white carrara marble" \
  -q 8 \
  --height 1680 \
  --width 1200 \
  --image-path "original_image.png" \
  --steps 20 \
  --seed 7102725

Instead of automatically generating the depth map based on a reference image, you can instead input the depth map yourself using the --depth-image-path, like so:

mflux-generate-depth \
  --prompt "A hallway made of white carrara marble" \
  -q 8 \
  --height 1680 \
  --width 1200 \
  --depth-image-path "depth_image.png" \
  --steps 20

To generate and export the depth map from an image without triggering the image generation, run the following command:

mflux-save-depth --image-path "your_image.jpg" -q 8

This will create a depth map and save it with the same name as your image but with a "_depth" suffix (e.g., "your_image_depth.png"). Quantization is supported for the Depth Pro model, however, output quality can very depend on the input image.

⚠️ Note: The Depth Pro model requires an additional 1.9GB download from Apple. The download happens automatically on first use.

⚠️ Note: Using the Depth tool requires an additional 33.92 GB download from black-forest-labs/FLUX.1-Depth-dev. The download happens automatically on first use.

🔄 Redux

The Redux tool is an adapter for FLUX.1 models that enables image variation generation similar to the image-to-image technique. It can reproduce an input image with slight variations, allowing you to refine and enhance existing images. Unlike the image-to-image technique which resumes the denoising process mid-way starting from the input image, the redux tool instead embeds the image and joins it with the T5 text encodings.

Image credit: Paris Bilal on Unsplash

Example

The following examples show how to use the Redux tool to generate variations:

mflux-generate-redux \
  --prompt "a grey statue of a cat on a white platform in front of a blue background" \
  --redux-image-paths "original.png" \
  --steps 20 \
  --height 1654 \
  --width 1154 \
  -q 8

You can also control the influence of each reference image by specifying strength values (between 0.0 and 1.0) using the --redux-image-strengths parameter:

mflux-generate-redux \
  --prompt "a grey statue of a cat on a white platform in front of a blue background" \
  --redux-image-paths "image1.png" "image2.png" \
  --redux-image-strengths 0.8 0.5 \
  --steps 20 \
  --height 1024 \
  --width 768 \
  -q 8

A higher strength value gives the reference image more influence over the final result. If you don't specify any strengths, a default value of 1.0 is used for all images.

There is a tendency for the reference image to dominate over the input prompt.

⚠️ Note: Using the Redux tool requires an additional 1.1GB download from black-forest-labs/FLUX.1-Redux-dev. The download happens automatically on first use.

🕹️ Controlnet

MFLUX has Controlnet support for an even more fine-grained control of the image generation. By providing a reference image via --controlnet-image-path and a strength parameter via --controlnet-strength, you can guide the generation toward the reference image.

mflux-generate-controlnet \
  --prompt "A comic strip with a joker in a purple suit" \
  --model dev \
  --steps 20 \
  --seed 1727047657 \
  --height 1066 \
  --width 692 \
  -q 8 \
  --lora-paths "Dark Comic - s0_8 g4.safetensors" \
  --controlnet-image-path "reference.png" \
  --controlnet-strength 0.5 \
  --controlnet-save-canny

This example combines the controlnet reference image with the LoRA Dark Comic Flux.

⚠️ Note: Controlnet requires an additional one-time download of ~3.58GB of weights from Huggingface. This happens automatically the first time you run the generate-controlnet command. At the moment, the Controlnet used is InstantX/FLUX.1-dev-Controlnet-Canny, which was trained for the dev model. It can work well with schnell, but performance is not guaranteed.

⚠️ Note: The output can be highly sensitive to the controlnet strength and is very much dependent on the reference image. Too high settings will corrupt the image. A recommended starting point a value like 0.4 and to play around with the strength.

Controlnet can also work well together with LoRA adapters. In the example below the same reference image is used as a controlnet input with different prompts and LoRA adapters active.

🔎 Upscale

The upscale tool allows you to increase the resolution of an existing image while maintaining or enhancing its quality and details. It uses a specialized ControlNet model that's trained to intelligently upscale images without introducing artifacts or losing image fidelity.

Under the hood, this is simply the controlnet pipeline with jasperai/Flux.1-dev-Controlnet-Upscaler, with a small modification that we don't process the image with canny edge detection.

Image credit: Kevin Mueller on Unsplash

How to use

mflux-upscale \
  --prompt "A gray owl on black background" \
  --steps 28 \
  --seed 42 \
  --height 1363 \
  --width 908 \
  -q 8 \
  --controlnet-image-path "low_res_image.png" \
  --controlnet-strength 0.6 

This will upscale your input image to the specified dimensions. The upscaler works best when increasing the resolution by a factor of 2-4x.

⚠️ Note: Depending on the capability of your machine, you might run out of memory when trying to export the image. Try the --vae-tiling flag to process the image in smaller chunks, which significantly reduces memory usage during the VAE decoding phase at a minimal cost to performance. This optimization may occasionally produce a subtle seam in the middle of the image, but it's often worth the tradeoff for being able to generate higher resolution images. You can also use --vae-tiling-split vertical to change the split direction from the default horizontal (top/bottom) to vertical (left/right).

Tips for Best Results

• For optimal results, try to maintain the same aspect ratio as the original image
• Prompting matters: Try to acculturate describe the image when upscaling
• The recommended --controlnet-strength is in the range between 0.5 to 0.7

🎛️ Dreambooth fine-tuning

As of release v.0.5.0, MFLUX has support for fine-tuning your own LoRA adapters using the Dreambooth technique.

This example shows the MFLUX training progression of the included training example which is based on the DreamBooth Dataset, also used in the mlx-examples repo.

Training configuration

To describe a training run, you need to provide a training configuration file which specifies the details such as what training data to use and various parameters. To try it out, one of the easiest ways is to start from the provided example configuration and simply use your own dataset and prompts by modifying the examples section of the json file.

Training example

A complete example (training configuration + dataset) is provided in this repository. To start a training run, go to the project folder cd mflux, and simply run:

mflux-train --train-config src/mflux/models/flux/variants/dreambooth/_example/train.json

By default, this will train an adapter with images of size 512x512 with a batch size of 1 and can take up to several hours to fully complete depending on your machine. If this task is too computationally demanding, see the section on memory issues for tips on how to speed things up and what tradeoffs exist.

During training, MFLUX will output training checkpoints with artifacts (weights, states) according to what is specified in the configuration file. As specified in the file train.json, these files will be placed in a folder on the Desktop called ~/Desktop/train, but this can of course be changed to any other path by adjusting the configuration. All training artifacts will be saved as self-contained zip file, which can later be pointed to resume an existing training run. To find the LoRA weights, simply unzip and look for the adapter safetensors file and use it as you would with a regular downloaded LoRA adapter.

Resuming a training run

The training process will continue to run until each training example has been used num_epochs times. For various reasons however, the user might choose to interrupt the process. To resume training for a given checkpoint, say 0001000_checkpoint.zip, simply run:

mflux-train --train-checkpoint 0001000_checkpoint.zip

This uses the --train-checkpoint command-line argument to specify the checkpoint file to resume from.

There are two nice properties of the training procedure:

• Fully deterministic (given a specified seed in the training configuration)
• The complete training state (including optimizer state) is saved at each checkpoint.

Because of these, MFLUX has the ability to resume a training run from a previous checkpoint and have the results be exactly identical to a training run which was never interrupted in the first place.

⚠️ Note: Everything but the dataset itself is contained within this zip file, as the dataset can be quite large. The zip file will contain configuration files which point to the original dataset, so make sure that it is in the same place when resuming training.

⚠️ Note: One current limitation is that a training run can only be resumed if it has not yet been completed. In other words, only checkpoints that represent an interrupted training-run can be resumed and run until completion.

"lora_layers": {
  "single_transformer_blocks": {
    "block_range": {
      "indices": [
        0,
        1,
        7,
        19,
        20
      ],
      ...
  },
...

🧠 Concept Attention

The Concept Attention feature allows you to visualize and understand how FLUX models focus on specific concepts within your prompts during image generation.

This implementation is based on the research paper "ConceptAttention: Diffusion Transformers Learn Highly Interpretable Features" by Helbling et al., which demonstrates that multi-modal diffusion transformers like FLUX learn highly interpretable representations that can be leveraged to generate precise concept localization maps.

MFLUX provides two concept attention tools:

1. Text-based Concept Analysis (mflux-concept): Analyzes attention patterns for a specific concept within your text prompt
2. Image-guided Concept Analysis (mflux-concept-from-image): Uses a reference image to guide concept attention analysis

Text-based Concept Analysis

This approach analyzes how the model attends to a specific concept mentioned in your prompt. The model generates an image while tracking attention patterns, then creates a heatmap showing where the model focused when processing your concept.

Example

mflux-concept \
  --prompt "A dragon on a hill" \
  --concept "dragon" \
  --model schnell \
  --steps 4 \
  --seed 9643208 \
  --height 720 \
  --width 1280 \
  --heatmap-layer-indices 15 16 17 18 \
  --heatmap-timesteps 0 1 2 3 \
  -q 4

This will generate the following image

This command will generate:

• The main image based on your prompt
• A concept attention heatmap showing where the model focused on the "dragon" concept
• Both images are automatically saved with appropriate naming

Image-guided Concept Analysis

This approach uses a reference image to guide the concept attention analysis. The model analyzes how a concept appears in the reference image and applies similar attention patterns to generate a new image that maintains those conceptual relationships.

Example

mflux-concept-from-image \
  --model schnell \
  --input-image-path "puffin.png" \
  --prompt "Two puffins are perched on a grassy, flower-covered cliffside, with one appearing to call out while the other looks on silently against a blurred ocean backdrop" \
  --concept "bird" \
  --steps 4 \
  --height 720 \
  --width 1280 \
  --seed 4529717 \
  --heatmap-layer-indices 15 16 17 18 \
  --heatmap-timesteps 0 1 2 3 \
  -q 4

This will generate the following image

Advanced Configuration

• --heatmap-layer-indices: Controls which transformer layers to analyze (default: 15-18). Different layers capture different levels of abstraction

• --heatmap-timesteps: Specifies which denoising steps to include in the analysis (default: all steps). Lower timestep values focus on early generation stages where broad composition is determined.

🚧 Current limitations

• Images are generated one by one.
• Negative prompts not supported.
• LoRA weights are only supported for the transformer part of the network.
• Some LoRA adapters does not work.
• Currently, the supported controlnet is the canny-only version.
• Dreambooth training currently does not support sending in training parameters as flags.
• In-Context Generation features currently only support a left-right image setup (reference image on left, generated image on right).

Optional Tool: Batch Image Renamer

With a large number of generated images, some users want to automatically rename their image outputs to reflect the prompts and configs.

The bundled tools/rename_images.py is an optional tool that is part with the project repo but not included in the mflux Python package due to additional dependencies that do not make sense to become standard project requirements.

The script uses KeyBERT (a keyword extraction library) to extract keywords from mflux exif metadata to update the image file names. We then use uv run to execute the script in an isolated env without affecting your mflux env.

Users who want to use or extend this tool to their own needs is encouraged to git clone the repo then uv run tools/rename_images.py or download the single-file standalone script and uv run your/path/rename_images.py.

This script's renaming logic can be customized to your needs. See uv run tools/rename_images.py --help for full CLI usage help.

💡Workflow Tips

• To hide the model fetching status progress bars, export HF_HUB_DISABLE_PROGRESS_BARS=1
• To opt-out of HuggingFace telemetry, export HF_HUB_DISABLE_TELEMETRY=1
• Use config files to save complex job parameters in a file instead of passing many --args
• Set up shell aliases for required args examples:
  • shortcut for dev model: alias mflux-dev='mflux-generate --model dev'
  • shortcut for schnell model and always save metadata: alias mflux-schnell='mflux-generate --model schnell --metadata'
  • shortcut for qwen model: alias mflux-qwen='mflux-generate-qwen'
• For systems with limited memory, use the --low-ram flag to reduce memory usage by constraining the MLX cache size and releasing components after use
• On battery-powered Macs, use --battery-percentage-stop-limit (or -B) to prevent your laptop from shutting down during long generation sessions
• When generating multiple images with different seeds, use --seed with multiple values or --auto-seeds to automatically generate a series of random seeds
• Use --stepwise-image-output-dir to save intermediate images at each denoising step, which can be useful for debugging or creating animations of the generation process

🔬 Cool research

• [ ] PuLID

🌱‍ Related projects

• Mflux-ComfyUI by @raysers
• MFLUX-WEBUI by @CharafChnioune
• mflux-fasthtml by @anthonywu
• mflux-streamlit by @elitexp

🙏 Acknowledgements

MFLUX would not be possible without the great work of:

• The MLX Team for MLX and MLX examples
• Black Forest Labs for the FLUX project
• Hugging Face for the Diffusers library implementation of Flux
• Depth Pro authors for the Depth Pro model
• The MLX community and all contributors and testers

⚖️ License

This project is licensed under the MIT License.