MFLUX: running Flux, Z-Image and Qwen Image locally on Apple silicon

The problem MFLUX solves: diffusers models without the CUDA assumption

Most reference implementations of current image models are written for CUDA and PyTorch. On a Mac that means either CPU inference, which is slow, or a translation layer that is not the same code path. MFLUX takes a different route: the README describes it as a line-by-line MLX port of several state-of-the-art generative image models from the Hugging Face Diffusers and Transformers libraries, with all models implemented from scratch in MLX and only tokenizers borrowed from Transformers. MLX is Apple's array framework, and the project pins mlx>=0.32.0,<0.33.0 on macOS in pyproject.toml. The target reader is someone with an Apple silicon machine who wants the model running on the GPU through MLX rather than a wrapped PyTorch build. The philosophy section is explicit that the code is kept minimal and explicit, in the style of a small reference implementation, which tells you what to expect: readable model code, not a serving stack.

How MFLUX is structured: one model family, one CLI entry point

The repository is organized under src/mflux/models, with a directory per family: z_image, krea2, flux2, ideogram4, ernie_image, lens, boogu, fibo, seedvr2, qwen, depth_pro and flux. Each family carries its own README and its own CLI module, and the top-level README points to the CLI entry points as the reference for the Python API. That layout explains the command naming: the install exposes many commands, and uv tool list is the documented way to see all of them. The models differ in size and type, from 3.8B to 20B parameters, some distilled and some base, and the README table lists release dates from Depth Pro in October 2024 through several 2026 entries. There is no single mflux generate command that abstracts over all of them, so choosing a model is a real decision rather than a flag. Shared behavior lives in src/mflux/models/common/README.md, which the project calls out for common CLI patterns and examples.

Installing MFLUX with uv and generating a first image

The README's installation path assumes uv. Install uv first if you do not have it, then install the tool. This places the mflux commands on your PATH rather than inside a project virtualenv.

uv tool install --upgrade mflux

The README then says to run uv tool list to see every available MFLUX CLI command. The first generation example uses the z-image-turbo model with a prompt, explicit dimensions, a seed, nine steps and 8-bit quantization.

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

Expect a model download on the first run; the README warns it can take some time. If the download fails with the hf_transfer error quoted in the README, reinstall with the extra package included.

uv tool install --upgrade mflux --with hf_transfer

For scripted use, the project documents a uv inline-dependency script. The model class is imported from its family module, constructed with a quantization level, and asked for an image.

#!/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 that file with uv run generate.py. The README also documents a Linux path for DGX or NVIDIA hardware using uv tool install --python 3.13 mflux, and pyproject.toml resolves mlx[cuda13] on Linux, so the Mac framing is the primary target rather than the only one.

Where MFLUX stops: no UI, no server, and a wide CLI surface

MFLUX is a library and a set of CLIs. It is not a web application, and the README does not claim otherwise; the related projects section points at separate efforts rather than describing a built-in interface. If you want a browser, a queue, or a REST endpoint, you are assembling that yourself around the Python API. The second limitation is surface area. The README notes that MFLUX supports a wide variety of CLI tools and options and suggests using a coding agent to navigate the CLI in 2026, asking it questions like "Can you help me generate an image using z-image?". That is an honest admission that the option space outgrew a single help page. Third, model choice carries real cost: a 20B base model such as Qwen Image is described in the table as large and slower, while the fast options are the distilled ones. Finally, quantization is a quality lever you set yourself. Nothing in the README claims that an 8-bit run matches a full-precision one, so treat -q as a trade you are making deliberately.

MFLUX compared with ComfyUI and the diffusers stack

The obvious alternative for local image generation is ComfyUI, a node-graph application that runs as a server with a browser front end. The difference is not only the interface. ComfyUI composes pipelines from nodes at runtime; MFLUX implements each model as explicit Python in MLX, and the README frames that as a deliberate choice. If your work is exploring prompts and wiring up workflows visually, ComfyUI fits better. If your work is calling a model from a script on a Mac and you want to read the implementation when something is off, MFLUX is the closer match. The other comparison is the Hugging Face Diffusers stack itself, which MFLUX ports from. Diffusers is broader, runs on multiple backends, and is the upstream source of the models; MFLUX is narrower and Mac-oriented, and its value is that the code path is MLX all the way down rather than a compatibility layer. Note that the related projects list in the README is where third-party MFLUX front ends are pointed to, so check there before building your own.

Maintenance, releases and what the MIT licence means here

The repository is not archived, and the last push was on 2026-09-11. Releases are frequent and versioned: v.0.19.1 on 2026-08-26, v.0.19.0 on 2026-08-18, and v.0.18.1 on 2026-08-07, with pyproject.toml declaring version 0.19.1 and requiring Python 3.10 or newer. The upgrade path is the same command used to install, since the README's install line includes the --upgrade flag. Budget for churn rather than a frozen API: the dependency list pins mlx tightly to a single minor range, and the model roster has grown across 2025 and 2026, so a model you rely on today may gain options or move between releases. The project is MIT licensed, which is permissive and places few conditions on reuse. That applies to MFLUX itself. The model weights it downloads carry their own licences from their publishers, and those are not covered by the repository's LICENSE file. Check the terms attached to whichever checkpoint you pull before using output commercially; this is not legal advice.

Editorial conclusion

Adopt MFLUX if you have an Apple silicon Mac, want local image generation without a Python project scaffold, and are comfortable picking a model family from the README table. Skip it if you need a browser UI, a hosted endpoint, or a single API that hides which model you are running. Before committing, verify that your chosen model's weights fit your unified memory at the quantization you intend, and run the install and first generation once to confirm the download and MLX backend work on your machine.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mflux-community/mflux on GitHub
4. README
5. Releases