# mflux: fourteen models in MLX, and documentation that hands you to a coding agent

> A from-scratch MLX port of image and video models for Apple silicon, where the CLI ships one binary per model, the NVIDIA section is a single command, and the README suggests asking an AI agent how to use it.

**mflux-community/mflux** — Apple MLX native implementations of state-of-the-art generative image & video models

- Repository: https://github.com/mflux-community/mflux
- Stars: 2,453 · Forks: 193
- Language: Python
- License: MIT
- Published: 2026-09-16 · Updated: 2026-09-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/mflux-community-mflux

## The documentation tells you to ask a coding agent how to use it

There is a note in the features section that is worth reading as a status report. Because the project supports a wide variety of command line tools and options, the file says the easiest way to navigate the CLI in 2026 is to use a coding agent such as Cursor or Claude Code, and it suggests asking a question like whether it can help generate an image using a given model.

That is an unusual thing for a README to say, and it is an admission that the option surface has outgrown the documentation. The size of the surface is explained by the packaging: each model gets its own console command rather than one command with a model argument, so the example is `mflux-generate-z-image-turbo` with flags for prompt, width, height, seed, steps and a short quantization flag, and the installed set of commands is discovered with `uv tool list`.

The install itself is one line through uv, and the Python route is a standalone script with inline dependency metadata that runs under `uv run`.

## Fourteen models, and only two of them can be trained

The models table carries fourteen rows with release dates, sizes, types, training flags and one-line descriptions. The training column has a value worth reading closely: it is set to yes for Z-Image and FLUX.2 and to no for the rest, with FLUX.1 carrying the note that it is legacy. LoRA finetuning is therefore available for two families, and the other twelve are inference only.

The size column needs the same attention, because three entries list a separate text encoder next to the model size. Lens is 3.8B with a 20B text encoder, Ming-Image is 6.15B with a 16B mixture of experts encoder, and Qwen Image 2.1 is 7.1B with an 8B encoder. In those three cases the transformer is the smaller half of the download.

Two rows are not generative models at all. SeedVR2 is described as an upscaling model and Depth Pro as Apple's depth estimation model, and both have a dash in the type column. FLUX.1 is retained for its editing and upscaling paths rather than for quality.

## The NVIDIA path is one command and no explanation

There is a section for DGX and NVIDIA, and it contains exactly one line:

```sh
uv tool install --python 3.13 mflux
```

That is the entire documentation for non-Apple hardware. The project describes itself as MLX native implementations for Mac, and the file offers no note on performance, supported cards, precision, or what happens when a model has no Apple-silicon-specific path.

The manifest is more informative than the documentation. The MLX dependency carries two markers, one for macOS and one pinned build for Linux carrying the CUDA 13 extra, so the package does install on Linux. That gap between what the dependency graph admits and what the README explains is the practical risk here: the path exists, and you are on your own with it.

Also worth noting is that the project has no homepage in its metadata, so the README and the package index are the whole published surface.

## A package the README says is missing is in the dependency list

The troubleshooting section documents a specific failure. If you hit a `ValueError` saying fast download using hf_transfer is enabled but the hf_transfer package is not available, the documented fix is to reinstall with the package included:

```sh
uv tool install --upgrade mflux --with hf_transfer
```

The dependency list in the project manifest already includes `hf-transfer` with a version range, as a runtime dependency rather than an optional extra. So the error message describes a state the manifest should not allow, and the `--with` form reinstalls something that was supposed to be there.

That points at a real class of problem rather than a typo: when a fast download path is switched on through an environment variable such as `HF_HUB_ENABLE_HF_TRANSFER`, the flag can be set in a shell profile or a launcher script without the corresponding package ever being installed into the tool's isolated environment. The fix is right even if the diagnosis of why it happened is unclear.

## Tokenizers arrive only on Python 3.13 and newer

The package supports Python 3.10 or newer, but the tokenizer dependency is conditional on the interpreter version, marked to install only where the Python version is 3.13 or above. Every other dependency is unconditional.

That marker is unusual for a project whose stated design is that models are implemented from scratch in MLX using only tokenizers borrowed from the Transformers library. On an older interpreter the tokenizer package is simply not installed, and whether that matters depends on which code paths pull it in.

The rest of the toolchain points the same direction. The project file recommends Python 3.13, and the NVIDIA install line asks for `--python 3.13` explicitly. The dependency set also carries hard floors rather than ranges at the top end, with torch, transformers, numpy and matplotlib all pinned below their next major, which keeps a machine from picking up an untested release but also means the package needs a rebuild when those majors land.

## Contributor setup asserts Apple silicon and may initialise a repository for you

The task runner recipes reveal the intended contributor machine. Creating the virtual environment depends on two expectations, one for an arm64 processor and one for uv being present, so the documented setup is Apple silicon only. The recipe installs the recommended Python with uv, creates the environment, syncs dependencies and installs pre-commit hooks.

The install recipe then checks whether the current directory is inside a git work tree and, if not, runs `git init` there. In a directory you meant to work in that is convenient; in the wrong directory it creates a repository you did not ask for.

Two smaller choices show how the project treats its own tooling. The lint recipe derives the ruff version by reading it out of the project file with a line of sed, described in a comment as the single source of truth, and runs it read-only through `uvx`. A separate recipe lints the task file itself by failing if its own formatter would change it. There is also a typo checker configuration at the root, and the root carries both a task file and a second file whose name is the same thing in capitals.

## Four agent configurations and a namespaced build

The repository root carries configuration for several coding assistants at once: an agents directory, a cursor directory, a coderabbit configuration, a greptile configuration, and an AGENTS.md. Whatever the project's position on generated contributions, the tooling assumption is that agents are part of the workflow rather than something arriving from outside it.

The build side is unusual in a good way. The build backend is uv's own, with the module named and marked as a namespace package, and the source exclude list carves out asset directories and training example images rather than shipping them. There is a stubs directory, a tests directory, a scripts directory, and a lock file.

One more detail in the manifest explains itself in a comment: the YAML library is declared even though it arrives through the model hub, so that a capability command with a YAML output format does not depend on a transitive dependency staying where it is. That is a small piece of engineering honesty, and it hints at a subcommand worth looking for when you want to inspect what the installed package can do.

## Conclusion

mflux fits a Mac user who wants a specific open image model running locally with quantized weights and no Python environment to manage, and who will follow a per-model README rather than expect one manual to cover the surface. Read four things first. Navigation is the project's own acknowledged problem, so budget time in a model's own README under `src/mflux/models/` rather than in the top-level file, and if you use an agent to help you drive the CLI, treat its suggestions as untested until you have run the command yourself. Size your disk from the text encoder as well as the model, because several entries list a separate encoder that dwarfs the transformer. Decide whether Linux is actually supported for you, since the manifest carries CUDA markers while the documentation for that path is one install line. And if you intend to finetune, note that only Z-Image and FLUX.2 are marked as trainable; everything else in the table is inference only.

## FAQ

### what is mflux

MFLUX is a line-by-line MLX port of generative image models from the Hugging Face Diffusers and Transformers libraries, with all models implemented from scratch in MLX and only the tokenizers taken from Transformers. It installs with `uv tool install --upgrade mflux` and runs on Apple silicon.

### How do I install mflux on a Mac?

Install uv first, then run `uv tool install --upgrade mflux`. The installed per-model commands are listed with `uv tool list`, and the first generation downloads the model, which the README notes can take some time.

### Can I finetune models with mflux?

Only two of the fourteen listed families are marked as trainable: Z-Image and FLUX.2. FLUX.1 is marked legacy and the rest are marked not trained, so LoRA finetuning applies to those two.

### Does mflux run on NVIDIA hardware?

The manifest carries a Linux dependency marked with the CUDA 13 extra, so the package installs there, and the README has a section for DGX and NVIDIA containing one line, `uv tool install --python 3.13 mflux`, with no further explanation of support or performance.

### What does the -q flag do in mflux commands?

It sets weight quantization, as the example `mflux-generate-z-image-turbo ... -q 8` shows, and the Python API exposes the same idea as `ZImageTurbo(quantize=8)`. Quantization and local model loading are listed as general features.

## Sources

- [Issues](https://github.com/mflux-community/mflux/issues)
- [License: MIT](https://github.com/mflux-community/mflux/blob/main/LICENSE)
- [mflux-community/mflux on GitHub](https://github.com/mflux-community/mflux)
- [README](https://github.com/mflux-community/mflux/blob/main/README.md)
- [Releases](https://github.com/mflux-community/mflux/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mflux-community-mflux