Metadata-Version: 2.3
Name: mlx-gen
Version: 0.18.3
Summary: Generative image model runtimes for MLX.
Keywords: flux,ai,ml,transformers,mlx,huggingface,apple-silicon,diffusers,qwen,qwen-image,seedvr2,z-image
Author: Filip Strand
Author-email: Filip Strand <strand.filip@gmail.com>
License: MIT License
         
         Copyright (c) 2026 Filip Strand
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: filelock>=3.20.1
Requires-Dist: fonttools>=4.60.2
Requires-Dist: huggingface-hub>=1.1.6,<2.0
Requires-Dist: hf-transfer>=0.1.9,<1.0
Requires-Dist: matplotlib>=3.9.2,<4.0
Requires-Dist: mlx>=0.27.0,<0.32.0 ; sys_platform == 'darwin'
Requires-Dist: mlx[cuda13]>=0.30.3,<0.32.0 ; sys_platform == 'linux'
Requires-Dist: numpy>=2.0.1,<3.0
Requires-Dist: opencv-python>=4.10.0,<5.0
Requires-Dist: piexif>=1.1.3,<2.0
Requires-Dist: pillow>=12.1.1
Requires-Dist: platformdirs>=4.0,<5.0
Requires-Dist: regex>=2024.11.6
Requires-Dist: requests>=2.32.4
Requires-Dist: safetensors>=0.4.4,<1.0
Requires-Dist: sentencepiece>=0.2.1,<1.0
Requires-Dist: tokenizers>=0.20.3 ; python_full_version >= '3.13'
Requires-Dist: toml>=0.10.2,<1.0
Requires-Dist: torch>=2.7.1,<3.0
Requires-Dist: torch>=2.8.0,<3.0 ; python_full_version >= '3.13'
Requires-Dist: tqdm>=4.66.5,<5.0
Requires-Dist: transformers>=5.0.0,<6.0
Requires-Dist: twine>=6.1.0,<7.0
Requires-Dist: urllib3>=2.6.0
Requires-Dist: protobuf>=4.25.0,<8.0
Requires-Dist: matplotlib>3.10,<4.0 ; extra == 'dev'
Requires-Dist: pytest>=8.3.0,<9.0 ; extra == 'dev'
Requires-Dist: pytest-timer>=1.0,<2.0 ; extra == 'dev'
Requires-Dist: mlx==0.31.0 ; sys_platform == 'darwin' and extra == 'dev'
Requires-Dist: mlx[cuda13]==0.30.3 ; sys_platform == 'linux' and extra == 'dev'
Maintainer: AbstractVision
Requires-Python: >=3.10
Project-URL: homepage, https://github.com/lpalbou/mlx-gen
Project-URL: upstream, https://github.com/filipstrand/mflux
Provides-Extra: dev
Description-Content-Type: text/markdown

# MLX-Gen

[![mlx-gen](https://img.shields.io/pypi/v/mlx-gen?label=mlx-gen&logo=pypi&logoColor=white)](https://pypi.org/project/mlx-gen/)
[![MLX](https://img.shields.io/pypi/v/mlx?label=MLX&logo=pypi&logoColor=white)](https://pypi.org/project/mlx/)
[![CI](https://github.com/lpalbou/mlx-gen/actions/workflows/tests.yml/badge.svg)](https://github.com/lpalbou/mlx-gen/actions/workflows/tests.yml)

### About

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

> [!IMPORTANT]
> MLX-Gen is an independent project forked from [mflux](https://github.com/filipstrand/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](#relationship-to-mflux)
- [💡 Philosophy](#-philosophy)
- [💿 Installation](#-installation)
- [Model Downloads And Preparation](#model-downloads-and-preparation)
- [Documentation](#documentation)
- [🎨 Models](#-models)
- [✨ Features](#-features)
- [🌱 Related projects](#related-projects)
- [🙏 Acknowledgements](#-acknowledgements)
- [⚖️ License](#%EF%B8%8F-license)

---

<a id="relationship-to-mflux"></a>

### Relationship to mflux

MLX-Gen started as a fork of [mflux](https://github.com/filipstrand/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](https://pypi.org/project/abstractvision/), the generative vision layer used with [AbstractCore](https://pypi.org/project/abstractcore/) in the wider [AbstractFramework](https://pypi.org/project/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](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`](https://github.com/astral-sh/uv?tab=readme-ov-file#installation), then run:

```sh
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:

```sh
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
```

![Puffin](src/mflux/assets/puffin.png)

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:

```sh
mlxgen download --model AbstractFramework/qwen-image-edit-2511-4bit

mlxgen generate \
  --model AbstractFramework/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:

```sh
# 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. Public card examples default to `AbstractFramework/<repo-name>` and include `python -m pip install -U mlx-gen` so Hugging Face readers can copy and paste a complete baseline setup.

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

### Documentation

- [Getting started](docs/getting-started.md): install MLX-Gen, discover the CLI, prepare a model, and run generation.
- [Architecture](docs/architecture.md): package shape, command boundaries, model-file lifecycle, and runtime failure contract.
- [API and CLI](docs/api.md): public command surface, Python integration notes, and compatibility entry points.
- [Model management](docs/model-management.md): explicit `download` and `prepare` behavior, runtime cache policy, and model-card creation.
- [Quantization](docs/quantization.md): q4/q8 behavior and Qwen mixed q4/q8 policy.
- [Hugging Face publishing](docs/huggingface-publishing.md): generated model cards, default `AbstractFramework/<repo-name>` usage, upload flow, and optional collection membership.
- [FAQ](docs/faq.md): common questions about `prepare`, downloads, package naming, and compatibility.
- [Troubleshooting](docs/troubleshooting.md): common setup and runtime errors.

<details>
<summary>Python API</summary>

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

```python
#!/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:

```sh
mlxgen download --model z-image-turbo
uv run generate.py
```

For more Python API inspiration, look at the [CLI entry points](src/mflux/models/z_image/cli/z_image_turbo_generate.py) for the respective models.
</details>

<details>
<summary>⚠️ Troubleshooting: hf_transfer error</summary>

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:

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

This will enable faster model downloads from Hugging Face.

</details>

<details>
<summary>DGX / NVIDIA (uv tool install)</summary>

```sh
uv tool install --python 3.13 mlx-gen
```
</details>

---

### 🎨 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](src/mflux/models/z_image/README.md) | Nov 2025 | 6B | Distilled & Base | Yes | Fast, small, very good quality and realism. |
|[FLUX.2](src/mflux/models/flux2/README.md) | Jan 2026 | 4B & 9B | Distilled & Base | Yes | Fastest + smallest with very good quality and edit capabilities. |
|[FIBO](src/mflux/models/fibo/README.md) | Oct 2025+ | 8B | Distilled & Base | No | Very good JSON-based prompt understanding. Has edit capabilities. |
|[SeedVR2](src/mflux/models/seedvr2/README.md) | Jun 2025 | 3B & 7B | — | No | Best upscaling model. |
|[Qwen Image](src/mflux/models/qwen/README.md) | Aug 2025+ | 20B | Base | No | Large model (slower); strong prompt understanding and world knowledge. Has edit capabilities |
|[Depth Pro](src/mflux/models/depth_pro/README.md) | Oct 2024 | — | — | No | Very fast and accurate depth estimation model from Apple. |
|[FLUX.1](src/mflux/models/flux/README.md) | 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](src/mflux/models/common/README.md) 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](https://cursor.com), [Claude Code](https://www.anthropic.com/claude-code), or similar). Ask questions like: “Can you help me generate an image using z-image?”


---

<a id="related-projects"></a>

### 🌱 Related projects

- [MindCraft Studio](https://themindstudio.cc/mindcraft#models) — macOS app built on mflux by [@shaoju](https://github.com/shaoju)
- [Mflux-ComfyUI](https://github.com/raysers/Mflux-ComfyUI) by [@raysers](https://github.com/raysers)
- [MFLUX-WEBUI](https://github.com/CharafChnioune/MFLUX-WEBUI) by [@CharafChnioune](https://github.com/CharafChnioune)
- [mflux-fasthtml](https://github.com/anthonywu/mflux-fasthtml) by [@anthonywu](https://github.com/anthonywu)
- [mflux-streamlit](https://github.com/elitexp/mflux-streamlit) by [@elitexp](https://github.com/elitexp)

---

### 🙏 Acknowledgements

MLX-Gen exists because of the great work of:

- The MLX Team for [MLX](https://github.com/ml-explore/mlx) and [MLX examples](https://github.com/ml-explore/mlx-examples)
- Black Forest Labs for the [FLUX project](https://github.com/black-forest-labs/flux)
- Bria for the [FIBO project](https://huggingface.co/briaai/FIBO)
- Tongyi Lab for the [Z-Image project](https://tongyi-mai.github.io/Z-Image-blog/)
- Qwen Team for the [Qwen Image project](https://qwen.ai/blog?id=a6f483777144685d33cd3d2af95136fcbeb57652&from=research.research-list)
- ByteDance, @numz and @adrientoupet for the [SeedVR2 project](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler)
- Hugging Face for the [Diffusers library implementations](https://github.com/huggingface/diffusers) 
- Depth Pro authors for the [Depth Pro model](https://github.com/apple/ml-depth-pro?tab=readme-ov-file#citation)
- [mflux](https://github.com/filipstrand/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](LICENSE).
