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
• 🦄 Contributors
• 🌱 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.

Python API

Create a standalone generate.py script with inline uv dependencies:

#!/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")

Run it with:

uv run generate.py

For more Python API inspiration, look at the CLI entry points for the respective models.

⚠️ Troubleshooting: hf_transfer error

If you encounter a ValueError: Fast download using 'hf_transfer' is enabled (HF_HUB_ENABLE_HF_TRANSFER=1) but 'hf_transfer' package is not available, you can install MFLUX with the hf_transfer package included:

uv tool install --upgrade mflux --with hf_transfer

This will enable faster model downloads from Hugging Face.

DGX / NVIDIA (uv tool install)

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), including LyCORIS LoKr on FLUX.1 and FLUX.2
• Metadata export + reuse, plus prompt file support
• Float16 compute for Apple M1-family GPUs on FLUX.2, Z-Image and Qwen-Image 2.1 (--compute-precision float16, see the common README)

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?”

🦄 Contributors

MFlux was originally created by Filip Strand in August 2024 and moved to this organisation in August 2026. It is maintained by:

Filip Strand
created mflux

Anthony Wu
toolchain, CI, releases, mflux.web

plz12345
devops, Krea 2, Boogu

Mariano Abad
ControlNets, training, Lens

Ian Scrivener
community, CUDA, model builds

Where the models and the main features came from, read from the merge history (gh pr view --json author,mergedAt):

Everyone else who fixed, tested and reviewed is in the contributor graph.

🌱 Related projects

Build a UI under mflux.web

We welcome independently distributed mflux.web.* implementations using Gradio, FastAPI, FastHTML, or any other UI framework. Each project can choose its own framework, dependencies, release schedule, and launch command.

mflux owns the parent initializer and inference implementation. Its package path extends across installed distributions, including separate editable checkouts. mflux.web is an implicit namespace package: Python combines the mflux/web/ directories contributed by independently installed UI packages. No intermediate distribution is required; neither core nor UI packages need to depend on mflux-web. The mflux-web distribution reserves the generic mflux-web name on PyPI; it does not provide the shared namespace and does not need to be installed. Its optional demo is just another child module, mflux.web.demo.

Your UI distribution owns a unique child, for example src/mflux/web/example_ui/__init__.py. With uv_build, configure module-name = "mflux.web.example_ui". Declare mflux and your chosen framework as dependencies with versions your UI supports. The minimum mflux version for split-directory installs must include this parent path extension.

Do not ship mflux/__init__.py, which belongs to core, or mflux/web/__init__.py, which must remain absent for the implicit namespace. Choose a unique child name to avoid collisions. PyPI distribution names can use hyphens; Python child names must be valid identifiers, such as example_ui. Reserving a PyPI distribution name does not reserve a Python namespace.

After installation in the same environment, consumers can use import mflux.web.example_ui. Installing a UI does not automatically launch it, discover applications, or mount routes. UI framework dependencies belong to the individual UI distributions; this namespace support adds none to mflux.

Community applications

• MindCraft Studio — macOS app built on mflux by @shaoju
• mflux-paint — native macOS inpaint/edit app (pywebview), 16 models across edit/inpaint/text-to-image, mask painting, multi-seed batch, by @Amo643
• Mflux-ComfyUI by @raysers
• MFLUX-WEBUI by @CharafChnioune
• mflux-fasthtml by @anthonywu
• mflux-streamlit by @elitexp
• mlx-taef — TAESD/TAEF tiny-autoencoder live previews and low-memory FLUX decode for mflux, by @IonDen
• mlx-teacache — TeaCache step-skipping to speed up FLUX generation in mflux, by @IonDen
• MLXBits Image Studio - A native macOS Swift app for FLUX, Krea 2, Z-Image and more!

🙏 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
• Baidu for the ERNIE-Image project
• Ideogram for the Ideogram 4 project
• Krea.ai for the Krea 2 project
• Qwen Team for the Qwen Image project
• Microsoft for the Lens (Turbo) model, and Comfy-Org for the weights repackage
• inclusionAI for the Ming-Image project
• The Boogu team for the Boogu 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.