image

MFLUX MLX CI Greptile: The War on Bugs

About

Run the latest state-of-the-art generative image models locally on your Mac in native MLX!

Table of contents

💡 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

Puffin

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.

Model Release date Size Type Training Description
Z-Image Nov 2025 6B Distilled & Base Yes Fast, small, very good quality and realism.
Krea 2 Jun 2026 12B Turbo (distilled) No Very good quality with a wide range of styles; good for creative exploration.
FLUX.2 Jan 2026 4B & 9B Distilled & Base Yes Fastest + smallest with very good quality and edit capabilities.
Ideogram 4 Jun 2026 9B Base No JSON-caption-native, typography-focused text-to-image generation.
ERNIE-Image Apr 2026 8B Distilled & Base No Single-stream DiT from Baidu. Vivid, high-contrast output.
Lens May 2026 3.8B (+20B TE) Turbo (distilled) No Dual-stream MMDiT from Microsoft with a GPT-OSS text encoder. Strong prompt adherence in 4 steps.
Boogu Image Jun 2026 10B Turbo (distilled) No DMD-distilled 4-step model with a photographic look and bilingual (EN/ZH) text rendering.
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), including LyCORIS LoKr on FLUX.1 and FLUX.2
  • 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 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?”

🌱 Related projects

🙏 Acknowledgements

MFLUX would not be possible without the great work of:

⚖️ License

This project is licensed under the MIT License.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for filipstrand from gravatar.com filipstrand

Credits

Author/Maintainer: Filip Strand

License

MIT License

Requires

Python >=3.10

Tags

flux ai ml transformers mlx huggingface apple-silicon diffusers qwen qwen-image seedvr2 z-image

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mflux-0.19.1.tar.gz (969.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mflux-0.19.1-py3-none-any.whl (1.3 MB view details)

Uploaded Python 3

File details

Details for the file mflux-0.19.1.tar.gz.

File metadata

  • Download URL: mflux-0.19.1.tar.gz
  • Upload date:
  • Size: 969.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mflux-0.19.1.tar.gz
Algorithm Hash digest
SHA256 f44577d4be2ec385c28f2107c41662eefc100f1c74df34e53f87fcd3dc217281
MD5 a74556f82c127827f6a6b573ce20bf6d
BLAKE2b-256 5e95b4944c86a0e255ea292ce8172bbb5bd1a4e66a60d12a194ec553607a5408

See more details on using hashes here.

Provenance

The following attestation bundles were made for mflux-0.19.1.tar.gz:

Publisher: release.yml on mflux-community/mflux

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mflux-0.19.1-py3-none-any.whl.

File metadata

  • Download URL: mflux-0.19.1-py3-none-any.whl
  • Upload date:
  • Size: 1.3 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mflux-0.19.1-py3-none-any.whl
Algorithm Hash digest
SHA256 e56f1e28e2cbad1153272ad87d3077f82442015f60214cdbc9b322c6003db513
MD5 bbfd53b7c9f14a32f1da5572cf302013
BLAKE2b-256 ef0eb0c08a5867e744317cfa400d336f02f6b2b7e32031288994384c2cbca583

See more details on using hashes here.

Provenance

The following attestation bundles were made for mflux-0.19.1-py3-none-any.whl:

Publisher: release.yml on mflux-community/mflux

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.19.1 This release

2 files

0.19.0

2 files

0.18.1

2 files

0.18.0

2 files

0.17.5

2 files

0.17.4

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.9

2 files

0.16.8

2 files

0.16.7

2 files

0.16.6

2 files

0.16.5

2 files

0.16.4

2 files

0.16.3

2 files

0.16.2

2 files

0.16.1

2 files

0.16.0

2 files

0.15.5

2 files

0.15.4

2 files

0.15.3

2 files

0.15.2

2 files

0.15.1

2 files

0.14.2

2 files

0.14.1

2 files

0.14.0

2 files

0.13.3

2 files

0.13.2

2 files

0.13.1

2 files

0.13.0

2 files

0.12.1

2 files

0.12.0

2 files

0.11.1

2 files

0.11.0

2 files

0.10.0

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

1 file

0.9.2

1 file

0.9.1

1 file

0.9.0

1 file

0.8.0

2 files

0.7.1

2 files

0.7.0

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.1

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.0

2 files

0.2.1

2 files

0.2.0

2 files

0.1.9

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page