mlx-gen 0.18.1

Generative image model runtimes for MLX.

MLX-Gen

About

Run state-of-the-art generative image models locally with native MLX.

[!IMPORTANT] MLX-Gen is an independent project forked from mflux. It is currently built on the mflux codebase, with full credit to Filip Strand and the original contributors, while publishing under the mlx-gen package name and exposing mlxgen as the application import path.

The project exists so compatibility fixes and capabilities can ship quickly for Apple Silicon workflows, including enabling Qwen Image/Edit support, Qwen/FLUX.2 image editing, quantized model packaging, local model loading, AbstractVision integration, and release cadence. We will continue to credit and upstream focused fixes where practical, but MLX-Gen is expected to evolve and diverge rapidly as its own package.

Table of contents

• Relationship to mflux
• 💡 Philosophy
• 💿 Installation
• Model Downloads And Preparation
• Documentation
• 🎨 Models
• ✨ Features
• 🌱 Related projects
• 🙏 Acknowledgements
• ⚖️ License

---

Relationship to mflux

MLX-Gen started as a fork of mflux, which established a clear MLX-native image generation stack. This repository preserves that foundation and remains MIT licensed.

The immediate reason for the independent package is practical: MLX-Gen can iterate faster on compatibility fixes and capabilities that affect real usage, including Qwen Image/Edit quantization layouts, FLUX.2 edit behavior, local model packaging, PyPI release cadence, and Apple Silicon validation. Some of those changes are proposed upstream as small PRs; others may remain MLX-Gen-specific as the project direction diverges.

MLX-Gen also exists to power AbstractVision, the generative vision layer used with AbstractCore in the wider AbstractFramework ecosystem. That gives the package its own product requirements while keeping general fixes available for upstream mflux contributions where practical.

For now, some internals still live under mflux.* while MLX-Gen evolves from its forked base. New application code should use the mlxgen command and import path.

The project intentionally keeps mflux vocabulary in parts of the codebase and metadata while that remains useful. This preserves compatibility for existing users and keeps a possible merge-back path open if the two projects converge again.

Most credit for the current codebase goes to Filip Strand and the original mflux contributors. Changes introduced after the MLX-Gen fork are maintained here by Laurent-Philippe Albou / AbstractVision. See ACKNOWLEDGEMENTS.md for project credits.

---

💡 Philosophy

MLX-Gen is an independent package for running generative image models on MLX. It prioritizes fast local iteration, practical Apple Silicon performance, and compatibility with current model releases without coupling every change to upstream release timing.

The implementation remains intentionally direct: model code is written in MLX, with Hugging Face libraries used for tokenizers and model downloads.

---

💿 Installation

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

uv tool install --upgrade mlx-gen

This package is published on PyPI as mlx-gen. The Python import for application code is mlxgen.

After installation, start with the MLX-Gen command help:

mlxgen --help

The public command surface is:

• mlxgen generate: generate or edit images with a cached or prepared model.
• mlxgen download: explicitly download a model snapshot into the Hugging Face cache.
• mlxgen prepare: create a reusable local MLX-Gen model folder, optionally quantized, and write a Hugging Face model card.

Use mlxgen prepare, not a separate save command, when you want a local quantized folder to reuse or upload.

To generate your first image, use mlxgen generate and choose the model with --model:

mlxgen download --model z-image-turbo

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

The same router is also available as mlx-gen, mlxgen-generate, and mlx-generate.

For image editing, pass input images with --image or --images; MLX-Gen routes to the right backend from the model and image inputs:

mlxgen download --model lpalbou/qwen-image-edit-2511-4bit

mlxgen generate \
  --model lpalbou/qwen-image-edit-2511-4bit \
  --image input.png \
  --prompt "Turn the room into a pencil sketch" \
  --steps 20 \
  --seed 42 \
  --output edited.png

If a local model path or custom repository name cannot be classified from its name, add --family qwen, --family flux2, --family fibo, or --family z-image. The router can also read model, image_path, and image_paths from --config-from-metadata.

Model Downloads And Preparation

MLX-Gen does not download model, tokenizer, LoRA, or Depth Pro files during generation. Generation is cache-only by default so applications can run predictable workflows without a network transfer starting in the middle of a job.

Use one of these explicit setup commands before generation:

# Download the required Hugging Face snapshot into the local cache.
mlxgen download --model Qwen/Qwen-Image

# Prepare a reusable local MLX-Gen model folder, optionally quantized.
mlxgen prepare \
  --model Qwen/Qwen-Image \
  --path ./models/qwen-image-8bit \
  --quantize 8

# Download the direct Apple Depth Pro weights used by depth workflows.
mlxgen download --model depth-pro

The commands have different outputs:

Command	Use it when	Writes a local model folder	Writes a Hugging Face card
mlxgen download	You want the original repository cached for generation.	No	No
mlxgen prepare	You want a reusable MLX-Gen folder, usually quantized, for local reuse or upload.	Yes	Yes
mlxgen generate	You want to run inference from cached or prepared files.	No	No

mlxgen download and mlxgen prepare are the commands that authorize network access. If you have Hugging Face's accelerated transfer backend available, you can optionally prefix those commands with HF_HUB_ENABLE_HF_TRANSFER=1 for faster downloads.

mlxgen prepare also writes a Hugging Face README.md model card into the prepared folder. The generated card cites the original model, mflux, MLX-Gen, the mlx-gen version that generated the card, the quantization policy, and the default contributor attribution.

If a required artifact is missing, MLX-Gen raises DownloadRequiredError with the exact command to run. See docs/model-management.md for details and docs/python-integration.md for in-process usage.

Documentation

• Getting started: install MLX-Gen, discover the CLI, prepare a model, and run generation.
• Architecture: package shape, command boundaries, model-file lifecycle, and runtime failure contract.
• API and CLI: public command surface, Python integration notes, and compatibility entry points.
• Model management: explicit download and prepare behavior, runtime cache policy, and model-card creation.
• Quantization: q4/q8 behavior and Qwen mixed q4/q8 policy.
• Hugging Face publishing: generated model cards, upload flow, and collection membership.
• FAQ: common questions about prepare, downloads, package naming, and compatibility.
• Troubleshooting: common setup and runtime errors.

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 = [
#   "mlx-gen",
# ]
# ///
from mlxgen.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:

mlxgen download --model z-image-turbo
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 explicitly enable HF_HUB_ENABLE_HF_TRANSFER=1 and encounter a ValueError because hf_transfer is not available, install MLX-Gen with the hf_transfer package included:

uv tool install --upgrade mlx-gen --with hf_transfer

This will enable faster model downloads from Hugging Face.

DGX / NVIDIA (uv tool install)

uv tool install --python 3.13 mlx-gen

---

🎨 Models

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

Model	Release date	Size	Type	Training	Description
Z-Image	Nov 2025	6B	Distilled & Base	Yes	Fast, small, very good quality and realism.
FLUX.2	Jan 2026	4B & 9B	Distilled & Base	Yes	Fastest + smallest with very good quality and edit capabilities.
FIBO	Oct 2025+	8B	Distilled & Base	No	Very good JSON-based prompt understanding. Has edit capabilities.
SeedVR2	Jun 2025	3B & 7B	—	No	Best upscaling model.
Qwen Image	Aug 2025+	20B	Base	No	Large model (slower); strong prompt understanding and world knowledge. Has edit capabilities
Depth Pro	Oct 2024	—	—	No	Very fast and accurate depth estimation model from Apple.
FLUX.1	Aug 2024	12B	Distilled & Base	No (legacy)	Legacy option with decent quality. Has edit capabilities with 'Kontext' model and upscaling support via ControlNet

---

✨ 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 MLX-Gen 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 — macOS app built on mflux by @shaoju
• Mflux-ComfyUI by @raysers
• MFLUX-WEBUI by @CharafChnioune
• mflux-fasthtml by @anthonywu
• mflux-streamlit by @elitexp

---

🙏 Acknowledgements

MLX-Gen exists because of 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
• mflux, Filip Strand, and the original mflux contributors and testers. MLX-Gen is currently based on that codebase and will keep acknowledging that foundation even as it evolves independently. Post-fork MLX-Gen changes are maintained by Laurent-Philippe Albou / AbstractVision.

---

⚖️ License

This project is licensed under the MIT License.