mflux

About

Run the latest state-of-the-art generative image models locally on your Mac in native MLX!

Table of contents

• 💡 Philosophy
• 💿 Installation
• 🎨 Models
• ✨ Features
• 🌱 Related projects
• 🙏 Acknowledgements
• ⚖️ License

💡 Philosophy

MFLUX is a line-by-line MLX port of several state-of-the-art generative image models from the Huggingface Diffusers and Huggingface Transformers libraries. All models are implemented from scratch in MLX, using only tokenizers from the Huggingface Transformers library. MFLUX is purposefully kept minimal and explicit, @karpathy style.

💿 Installation

If you haven't already, install uv, then run:

uv tool install --upgrade mflux

After installation, the following command shows all available MFLUX CLI commands:

uv tool list 

To generate your first image using, for example, the z-image-turbo model, run

mflux-generate-z-image-turbo \
  --prompt "A puffin standing on a cliff" \
  --width 1280 \
  --height 500 \
  --seed 42 \
  --steps 9 \
  -q 8

The first time you run this, the model will automatically download which can take some time. See the model section for the different options and features, and the common README for shared CLI patterns and examples.

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "mflux",
# ]
# ///
from mflux.models.z_image import ZImageTurbo

model = ZImageTurbo(quantize=8)
image = model.generate_image(
    prompt="A puffin standing on a cliff",
    seed=42,
    num_inference_steps=9,
    width=1280,
    height=500,
)
image.save("puffin.png")

uv run generate.py

uv tool install --upgrade mflux --with hf_transfer

uv tool install --python 3.13 mflux

🎨 Models

MFLUX supports the following model families. They have different strengths and weaknesses; see each model’s README for full usage details.

✨ Features

General

• Quantization and local model loading
• LoRA support (multi-LoRA, scales, library lookup)
• Metadata export + reuse, plus prompt file support

Model-specific highlights

• Text-to-image and image-to-image generation.
• LoRA finetuning
• In-context editing, multi-image editing, and virtual try-on
• ControlNet (Canny), depth conditioning, fill/inpainting, and Redux
• Upscaling (SeedVR2 and Flux ControlNet)
• Depth map extraction and FIBO prompt tooling (VLM inspire/refine)

See the common README for detailed usage and examples, and use the model section above to browse specific models and capabilities.

[!NOTE] As MFLUX supports a wide variety of CLI tools and options, the easiest way to navigate the CLI in 2026 is to use a coding agent (like Cursor, Claude Code, or similar). Ask questions like: “Can you help me generate an image using z-image?”

🌱 Related projects

• MindCraft Studio by @shaoju
• 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
• Bria for the FIBO project
• Tongyi Lab for the Z-Image project
• Qwen Team for the Qwen Image project
• ByteDance, @numz and @adrientoupet for the SeedVR2 project
• Hugging Face for the Diffusers library implementations
• 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.