Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

H3 Image MLX in liquid-glass lettering on a blue gradient

This banner was generated end to end with MiniMax H3 Image using H3 Image MLX.

H3 Image MLX

English · 简体中文

Follow @anion_ex on X PyPI version Requires Python 3.11 or newer Package license: Apache-2.0 AND MIT

Quick start · Image editing · How it works · Benchmarks · Usage · Performance

Generate and edit images on an Apple Silicon Mac with MiniMax H3 Image. Optimized for fast inference, with 4K generation using around 7 GB of peak inference-process memory. Available through a CLI and Python API, ready to use out of the box.

If you find this repository useful, feel free to 🌟 & fork~

Highlights

  • Native Apple Silicon inference. Built on MLX to take advantage of your Mac's compute capabilities, H3 Image runs locally with text-to-image generation and multi-image editing.
  • W8A8 quantization and Metal acceleration. Reduce weight memory usage with a portable MLX inference path, plus W8A8 Metal TensorOps acceleration on supported chips. Compatible with M1–M4.
  • Staged inference with on-demand block loading. Each stage runs in a separate process to release its memory on completion. Denoiser weights can be read one block at a time, greatly reducing peak memory usage and leaving more room for other apps.

For reference, in our 1024×1024 generation benchmark, streaming reduced the peak inference-process footprint from 21.16 GB to 2.53 GB, with median runtime increasing from 19.90 s to 28.82 s. Benchmark conditions and results

Benchmark results

Same-machine controlled comparison

The same M5 Pro MacBook (48 GB), weight files, teapot prompt, initial noise and six-step sigma grid. Each group has one warmup and three measured generations.

Resolution MLX DiT mode ComfyUI time (s) MLX time (s) Speed ratio ComfyUI peak (GB) MLX peak (GB)
1024×1024 resident 87.15 19.90 4.38× 31.29 21.16
1024×1024 stream 87.15 28.82 3.02× 31.29 2.53
2048×2048 resident 134.17 57.43 2.34× 38.21 22.27
2048×2048 stream 134.17 67.06 2.00× 38.21 3.48
4096×4096 stream 570.59 317.29 1.80× 42.31 7.18

Time is the median complete generation request. Memory is the kernel-recorded single-process physical-footprint peak, including warmup, in decimal GB. Speed ratio = local ComfyUI time ÷ MLX time.

This compares complete pipelines: ComfyUI's default text encoder runs on CPU; MLX uses GPU. The main table reproduces the community configuration. The additional native INT8 DiT path, pinned versions and measurement method are in the full benchmark records, with source JSON in this repository.

Supplementary community measurements

Device / memory Pipeline DiT mode Resolution Time (s) Process peak (GB) Source
M5 MacBook Air / 16 GB H3 Image MLX stream 1024×1024 70.51 2.48 arielfikru
M5 MacBook Air / 16 GB H3 Image MLX stream 2048×2048 240.78 2.78 arielfikru
M5 Pro Mac mini / 64 GB ComfyUI + MPS INT8 — 1024×1024 89.55 31.42 pratikgx
M5 Pro Mac mini / 64 GB ComfyUI + MPS INT8 — 2048×2048 164.90 36.21 pratikgx
M5 Pro Mac mini / 64 GB ComfyUI + MPS INT8 — 4096×4096 547.31 48.78 pratikgx

Independent measurements on different machines, retaining contributors' original results. Run counts and measurement methods are in the full records, alongside the earlier M5 Pro runs.

Six H3 Image MLX examples: a feast, a fox in flight, a celadon tea set, a woodland chapel, a watercolor illustration and a rainy-night watchmaker.

Generated locally with H3 Image MLX: food, wildlife, product photography, architecture, illustration and a 4K watchmaker portrait. Click the collage to view it at full size.

Generate your first image

Use Python 3.11 or later on a Mac with Metal. Allow 49.30 GB of disk space for a fresh model download. Check the MiniMax model license for regional and usage restrictions.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'h3-image-mlx==0.1.0a2'

h3-image-mlx fetch --models ./models
h3-image-mlx generate --models ./models --output teapot.png \
  --prompt 'A yellow enamel teapot and a white cup on a blue wooden table.'

This writes a 1024×1024 RGB PNG. Set --width and --height to change the size. Each dimension accepts multiples of 32 from 256 through 4096.

We recommend trying weight prefetch and asynchronous evaluation when using --dit-mode stream, especially on a 16 GB M5 Mac. Both switches are off by default. They overlap weight reads with GPU work while retaining the six-step sampler. On the contributor's M5 Air, 1024×1024 generation fell from 59.8 s to 34.8–43.6 s, with a reported peak footprint of about 2.5 GB and pixel-identical outputs. Measurements and trade-offs

Available from 0.1.0a2; upgrade and enable both switches for this command:

python -m pip install --upgrade 'h3-image-mlx==0.1.0a2'
H3_ASYNC=1 H3_PREFETCH=1 h3-image-mlx generate \
  --models ./models --dit-mode stream --output teapot.png \
  --prompt 'A yellow enamel teapot and a white cup on a blue wooden table.'

Usage guide: CLI, Python and existing weights · Performance guide: switches, caching and profiling

Edit with reference images

To replace the cup in teapot.png with a bird from your own photo, save the photo as bird.png. Number the pictures in your prompt in the order you pass them on the command line.

h3-image-mlx generate --models ./models --output edit.png \
  --reference teapot.png --reference bird.png \
  --prompt 'Edit <Picture 1>. Replace the white cup with the bird from <Picture 2>. Keep the teapot and table.'

You can pass up to 16 references. On an M5 Pro, we completed one- and two-reference edits. The 16-reference test reached the third of six denoising steps before cancellation. Validation notes

How it works

The pipeline reduces memory use at three levels: between model stages, within the denoiser, and during image decoding.

H3 Image MLX pipeline: encode the prompt, stream denoiser weights, then decode overlapping image tiles. Each stage releases its model memory before the next starts.

  • Run one stage at a time. Text encoding, denoising and VAE decoding run in separate processes. Each saves its intermediate output and exits before the next loads its weights, so the three models do not need to stay in memory together. Editing adds a reference-image VAE encoding stage before denoising.
  • Keep quantized projections compact. The runtime reads Comfy-Org's INT8 ConvRot weights directly. Activations are rotated and dynamically quantized to INT8 before quantized linear projections. Supported chips use W8A8 Metal TensorOps; the portable backend evaluates the same quantized projections with tiled standard MLX operations. Other operations retain their appropriate floating-point precision.
  • Load denoiser weights as needed. In stream mode, tensors are read from safetensors as each transformer block runs, rather than cached for all six steps. Denoising still operates on the full image's latent sequence. resident mode caches weights to reduce repeated reads. The runtime also precomputes the steps' AdaLN modulation values from the compressed curves in Comfy-Org's pruned checkpoint, then releases the setup weights.
  • Decode in overlapping tiles. The VAE decodes small groups of latent tiles and blends their overlapping edges into the output image, limiting decoder working memory at high resolutions.

Streaming trades additional weight reads for a smaller memory footprint. Peak usage still includes activations, attention buffers and image buffers, so resolution and reference-image count matter. See the benchmark results for the measured trade-off.

Hardware and memory

M5/M6 select W8A8 Metal TensorOps by default; M1–M4 use the portable MLX backend. Use --dit-mode stream for lower memory usage or --dit-mode resident to retain denoiser weights between steps. Hardware validation and automatic mode selection

Documentation

Document Contents
Usage guide CLI parameters, reference editing, Python API and existing weights
Performance guide Recommended streaming switches, hardware modes, embedding cache and profiling
Benchmarks Measurements, environments and source JSON
Validation notes Completed checks and remaining hardware coverage

Credits and licenses

MiniMax developed H3 Image and supplies the VAE configuration. Comfy-Org provides the quantized weights. The three W8A8 Metal kernel files come from mlx-serve and retain their MIT license. This project’s runtime code uses Apache-2.0.

About

I'm anionex, an AI-native developer who once ranked No. 3 on GitHub's global developer trending list, with more than 18.7k stars across my projects. If you would like to follow my future work, follow me on X or GitHub.

Metadata

Release files for h3-image-mlx 0.1.0a2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for h3-image-mlx 0.1.0a2
File Size Uploaded Provenance Actions
h3_image_mlx-0.1.0a2.tar.gz 43.4 kB With provenance Details for h3_image_mlx-0.1.0a2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for h3-image-mlx 0.1.0a2
File Interpreter ABI Platform Actions
h3_image_mlx-0.1.0a2-py3-none-any.whl Python 3 none any Details for h3_image_mlx-0.1.0a2-py3-none-any.whl

Total release size: 85.7 kB

Release files / h3_image_mlx-0.1.0a2.tar.gz

Download URL h3_image_mlx-0.1.0a2.tar.gz
Size 43.4 kB
Tags Source
SHA-256 checksum
How to use checksums
84bcae23ad85fd0791f88885578f31dda27eef7fc7c842ccd0420d83006c914e
BLAKE2b-256 checksum
How to use checksums
60b82a06ecfa9ef6cf01f9dcfe3ab5a0ba7b6a8d3b9c54585d24690aae958e9c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / h3_image_mlx-0.1.0a2-py3-none-any.whl

Download URL h3_image_mlx-0.1.0a2-py3-none-any.whl
Size 42.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1c0d9467143b7aad9464ab23007b35fb68f0338aab8df42d6cb835b49e661a72
BLAKE2b-256 checksum
How to use checksums
d2209c5a3e93e6b27e9c47b1b172e1339baaea02864e709188c7640de16992e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for h3-image-mlx 0.1.0a2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for h3_image_mlx-0.1.0a2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

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