The Problem

Running state-of-the-art generative image models locally on Apple Silicon is typically slow or impossible because most implementations rely on CUDA. MFLUX solves this by providing line-by-line MLX ports of models like FLUX.2, Z-Image, and Qwen3-VL, letting you generate images natively on a Mac without a GPU cloud.

What This Does

MFLUX is a from-scratch MLX implementation of several diffusion models, ported from Hugging Face Diffusers/Transformers. The repo contains model definitions (src/mflux/models/), a CLI (src/mflux/cli/), a callback system for monitoring generation (src/mflux/callbacks/), and a training pipeline for LoRA fine-tuning (src/mflux/models/common/training/). It supports text-to-image, image editing, inpainting, ControlNet, and LoRA training.

The codebase is substantial — 627 Python files, 1,752 functions, 496 classes — and covers the full stack from weight mapping to VAE tiling. The CLI is the primary interface, with per-model entry points like mflux-generate-z-image-turbo and mflux-generate-flux2.

How It Is Wired

Execution starts at CLI entry points. For example, main in src/mflux/cli/completions/install.py reaches 412 functions, and the core parse_args function (defined in src/mflux/cli/parser/parsers.py) is called from 57 places. The call graph shows resolve in src/mflux/models/common/resolution/config_resolution.py is the most-connected function, called from 72 places — it handles model configuration resolution and is a high-blast-radius change point.

The heaviest hub is WeightTarget in the weight mapping module, called 468 times from get_vae_mapping and 314 times from get_transformer_mapping. This is where model weights get mapped from Hugging Face checkpoints to MLX tensors. The callbacks system (src/mflux/callbacks/callback_registry.py) routes through 197 functions and handles file I/O for saving intermediate results.

The module graph shows no circular dependencies, but there are high-instability modules: src/mflux/models/common/schedulers/__init__.py and src/mflux/models/common_models/qwen3_vl/qwen3_vl_vision_block.py have instability 1, meaning they depend on many modules but nothing depends on them — they're leaf nodes that are easy to change in isolation.

File I/O happens in 105 functions, with src/mflux/utils/image_util.py handling image save/load and src/mflux/models/common/training/state/training_spec.py managing training state persistence. External commands are run from src/mflux/cli/completions/install.py.

How To Use It

Setup — Install with uv (the README specifies this):

uv tool install --upgrade mflux

Configuration — No config files required. Model weights download automatically from Hugging Face on first run. If you use hf_transfer for faster downloads, install with --with hf_transfer.

Running it — Generate an image with the CLI:

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

Or use the Python API directly, as shown in the README's generate.py example with ZImageTurbo.

Real-World Use

A designer on a Mac wants to prototype variations of a product shot without waiting for cloud GPU queues. They run mflux-generate-flux2-klein --prompt "minimalist desk lamp, studio lighting" --seed 7 -q 4 and get a 4-bit quantized result in seconds. For a production pipeline, they'd use the Python API to batch-generate with different seeds, then run LoRA training on their own product images via mflux-train to fine-tune the model.

Code Health & Issues

Static analysis found 60 issues (6 high, 54 medium). The high-severity items:

  • High — Duplicated code blocks — 1,082 repeated 6-line blocks across 186 files. Shared helpers should be extracted.
  • High — Deep nesting (30 instances) — Files like src/mflux/models/common/resolution/path_resolution.py reach indentation depth 8, making control flow hard to follow.
  • Medium — Files opened without context managers (8) — src/mflux/cli/parser/parsers.py and src/mflux/models/common/training/runner.py risk handle leaks.
  • Medium — Broad exception handling (2) — src/mflux/utils/metadata_builder.py and src/mflux/utils/version_util.py swallow errors indiscriminately.
  • Medium — High branching density (12) — src/mflux/cli/parser/parsers.py has 31 branch points over 82 lines.

The CI workflow has a high issue: GitHub Actions are pinned to tags (astral-sh/setup-uv@v4) rather than commit SHAs, which is a supply-chain risk. The workflow also lacks least-privilege permissions declarations and a dependency vulnerability scan. There's no lockfile, so builds aren't reproducible. Tests exist (90 files) and CI runs on GitHub Actions.

The Bottom Line

MFLUX is a serious, well-structured MLX implementation with broad model coverage and a working training pipeline. The main risks are the duplicated code and the CI supply-chain hygiene. For Mac users who need local generative image models, this is the most complete option available — worth adopting despite the maintainability debt.