{"id":14150875,"url":"https://github.com/filipstrand/mflux","last_synced_at":"2026-04-01T22:26:34.559Z","repository":{"id":252846244,"uuid":"840672252","full_name":"filipstrand/mflux","owner":"filipstrand","description":"MLX native implementations of state-of-the-art generative image models","archived":false,"fork":false,"pushed_at":"2026-03-23T13:08:20.000Z","size":160831,"stargazers_count":1921,"open_issues_count":72,"forks_count":131,"subscribers_count":20,"default_branch":"main","last_synced_at":"2026-03-24T09:24:53.625Z","etag":null,"topics":["ai","apple-silicon","diffusers","fibo","flux","huggingface","ml","mlx","qwen","qwen-image","seedvr2","transformers","z-image"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/filipstrand.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-08-10T10:30:00.000Z","updated_at":"2026-03-24T07:42:09.000Z","dependencies_parsed_at":"2024-09-18T01:57:22.192Z","dependency_job_id":"57a44b2e-5eda-4872-82af-f49f97fa9222","html_url":"https://github.com/filipstrand/mflux","commit_stats":null,"previous_names":["filipstrand/mflux"],"tags_count":53,"template":false,"template_full_name":null,"purl":"pkg:github/filipstrand/mflux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filipstrand%2Fmflux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filipstrand%2Fmflux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filipstrand%2Fmflux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filipstrand%2Fmflux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filipstrand","download_url":"https://codeload.github.com/filipstrand/mflux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filipstrand%2Fmflux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","apple-silicon","diffusers","fibo","flux","huggingface","ml","mlx","qwen","qwen-image","seedvr2","transformers","z-image"],"created_at":"2024-08-17T04:00:37.914Z","updated_at":"2026-04-01T22:26:34.543Z","avatar_url":"https://github.com/filipstrand.png","language":"Python","funding_links":[],"categories":["Python","HarmonyOS","ai","Demo","Vision \u0026 Multimodal"],"sub_categories":["Windows Manager","2024"],"readme":"![image](src/mflux/assets/logo.jpg)\n\n[![MFLUX](https://img.shields.io/pypi/v/mflux?label=MFLUX\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/mflux/)\n[![MLX](https://img.shields.io/pypi/v/mlx?label=MLX\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/mlx/)\n[![CI](https://github.com/filipstrand/mflux/actions/workflows/tests.yml/badge.svg)](https://github.com/filipstrand/mflux/actions/workflows/tests.yml)\n\n### About\n\nRun the latest state-of-the-art generative image models locally on your Mac in native MLX!\n\n### Table of contents\n\n- [💡 Philosophy](#-philosophy)\n- [💿 Installation](#-installation)\n- [🎨 Models](#-models)\n- [✨ Features](#-features)\n- [🌱 Related projects](#related-projects)\n- [🙏 Acknowledgements](#-acknowledgements)\n- [⚖️ License](#%EF%B8%8F-license)\n\n---\n\n### 💡 Philosophy\n\nMFLUX is a line-by-line MLX port of several state-of-the-art generative image models from the [Huggingface Diffusers](https://github.com/huggingface/diffusers) and [Huggingface Transformers](https://github.com/huggingface/transformers) libraries. All models are implemented from scratch in MLX, using only tokenizers from the [Huggingface Transformers](https://github.com/huggingface/transformers) library. MFLUX is purposefully kept minimal and explicit, [@karpathy](https://gist.github.com/awni/a67d16d50f0f492d94a10418e0592bde?permalink_comment_id=5153531#gistcomment-5153531) style.\n\n---\n\n### 💿 Installation\nIf you haven't already, [install `uv`](https://github.com/astral-sh/uv?tab=readme-ov-file#installation), then run:\n\n```sh\nuv tool install --upgrade mflux\n```\n\nAfter installation, the following command shows all available MFLUX CLI commands: \n\n```sh\nuv tool list \n```\n\nTo generate your first image using, for example, the z-image-turbo model, run\n\n```\nmflux-generate-z-image-turbo \\\n  --prompt \"A puffin standing on a cliff\" \\\n  --width 1280 \\\n  --height 500 \\\n  --seed 42 \\\n  --steps 9 \\\n  -q 8\n```\n\n![Puffin](src/mflux/assets/puffin.png)\n\nThe first time you run this, the model will automatically download which can take some time. See the [model section](#-models) for the different options and features, and the [common README](src/mflux/models/common/README.md) for shared CLI patterns and examples.\n\n\u003cdetails\u003e\n\u003csummary\u003ePython API\u003c/summary\u003e\n\nCreate a standalone `generate.py` script with inline `uv` dependencies:\n\n```python\n#!/usr/bin/env -S uv run --script\n# /// script\n# requires-python = \"\u003e=3.10\"\n# dependencies = [\n#   \"mflux\",\n# ]\n# ///\nfrom mflux.models.z_image import ZImageTurbo\n\nmodel = ZImageTurbo(quantize=8)\nimage = model.generate_image(\n    prompt=\"A puffin standing on a cliff\",\n    seed=42,\n    num_inference_steps=9,\n    width=1280,\n    height=500,\n)\nimage.save(\"puffin.png\")\n```\n\nRun it with:\n\n```sh\nuv run generate.py\n```\n\nFor 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.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e⚠️ Troubleshooting: hf_transfer error\u003c/summary\u003e\n\nIf 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:\n\n```sh\nuv tool install --upgrade mflux --with hf_transfer\n```\n\nThis will enable faster model downloads from Hugging Face.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDGX / NVIDIA (uv tool install)\u003c/summary\u003e\n\n```sh\nuv tool install --python 3.13 mflux\n```\n\u003c/details\u003e\n\n---\n\n### 🎨 Models\n\nMFLUX supports the following model families. They have different strengths and weaknesses; see each model’s README for full usage details.\n\n| Model | Release date | Size | Type | Training | Description |\n| --- | --- | --- | --- | --- | --- |\n|[Z-Image](src/mflux/models/z_image/README.md) | Nov 2025 | 6B | Distilled \u0026 Base | Yes | Fast, small, very good quality and realism. |\n|[FLUX.2](src/mflux/models/flux2/README.md) | Jan 2026 | 4B \u0026 9B | Distilled \u0026 Base | Yes | Fastest + smallest with very good qaility and edit capabilities. |\n|[FIBO](src/mflux/models/fibo/README.md) | Oct 2025+ | 8B | Distilled \u0026 Base | No | Very good JSON-based prompt understanding. Has edit capabilities. |\n|[SeedVR2](src/mflux/models/seedvr2/README.md) | Jun 2025 | 3B \u0026 7B | — | No | Best upscaling model. |\n|[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 |\n|[Depth Pro](src/mflux/models/depth_pro/README.md) | Oct 2024 | — | — | No | Very fast and accurate depth estimation model from Apple. |\n|[FLUX.1](src/mflux/models/flux/README.md) | Aug 2024 | 12B | Distilled \u0026 Base | No (legacy) | Legacy option with decent quality. Has edit capabilities with 'Kontext' model and upscaling support via ControlNet |\n\n---\n\n### ✨ Features\n\n**General**\n- Quantization and local model loading\n- LoRA support (multi-LoRA, scales, library lookup)\n- Metadata export + reuse, plus prompt file support\n\n**Model-specific highlights**\n- Text-to-image and image-to-image generation.\n- LoRA finetuning\n- In-context editing, multi-image editing, and virtual try-on\n- ControlNet (Canny), depth conditioning, fill/inpainting, and Redux\n- Upscaling (SeedVR2 and Flux ControlNet)\n- Depth map extraction and FIBO prompt tooling (VLM inspire/refine)\n\nSee 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.\n\n\u003e [!NOTE]\n\u003e 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](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?”\n\n\n---\n\n\u003ca id=\"related-projects\"\u003e\u003c/a\u003e\n\n### 🌱 Related projects\n\n- [MindCraft Studio](https://themindstudio.cc/mindcraft#models) by [@shaoju](https://github.com/shaoju)\n- [Mflux-ComfyUI](https://github.com/raysers/Mflux-ComfyUI) by [@raysers](https://github.com/raysers)\n- [MFLUX-WEBUI](https://github.com/CharafChnioune/MFLUX-WEBUI) by [@CharafChnioune](https://github.com/CharafChnioune)\n- [mflux-fasthtml](https://github.com/anthonywu/mflux-fasthtml) by [@anthonywu](https://github.com/anthonywu)\n- [mflux-streamlit](https://github.com/elitexp/mflux-streamlit) by [@elitexp](https://github.com/elitexp)\n\n---\n\n### 🙏 Acknowledgements\n\nMFLUX would not be possible without the great work of:\n\n- The MLX Team for [MLX](https://github.com/ml-explore/mlx) and [MLX examples](https://github.com/ml-explore/mlx-examples)\n- Black Forest Labs for the [FLUX project](https://github.com/black-forest-labs/flux)\n- Bria for the [FIBO project](https://huggingface.co/briaai/FIBO)\n- Tongyi Lab for the [Z-Image project](https://tongyi-mai.github.io/Z-Image-blog/)\n- Qwen Team for the [Qwen Image project](https://qwen.ai/blog?id=a6f483777144685d33cd3d2af95136fcbeb57652\u0026from=research.research-list)\n- ByteDance, @numz and @adrientoupet for the [SeedVR2 project](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler)\n- Hugging Face for the [Diffusers library implementations](https://github.com/huggingface/diffusers) \n- Depth Pro authors for the [Depth Pro model](https://github.com/apple/ml-depth-pro?tab=readme-ov-file#citation)\n- The MLX community and all [contributors and testers](https://github.com/filipstrand/mflux/graphs/contributors)\n\n---\n\n### ⚖️ License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilipstrand%2Fmflux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffilipstrand%2Fmflux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilipstrand%2Fmflux/lists"}