Using GGUF (quantized) models

What comes as GGUF and what doesn't

A MiniMax H3 model has several parts. Only the parts with large weights are published as GGUF; the rest come from the official model.

A tokenizer is a few MB of vocabulary, not weights, so there is no GGUF of it. The VAEs aren't published as GGUF either, but unsloth and Comfy-Org publish them as single safetensors files (the video VAE in FP16, half the size), which H3cApp reads too.

Setting up with the download wizard (recommended)

1. Open the wizard. Use “Set Up the MiniMax-H3 Model”, shown at first launch; Model Manager's “Download and Add…” opens it too.
2. Choose “GGUF (quantized) and needed parts” under “What to download”.
3. Pick a file for each part. With the default sources, these are recommended:

   Part	Recommended	Smaller
   DiT (FL2VA)	unsloth's Q8_0 (21.4 GB, tested)	Q4_K (11.4 GB)
   Text encoder	unsloth's H3-specific Q4_K_M (18.2 GB, 50 layers, with the image part)	—
   VAEs	unsloth's VAEs (5.9 GB, tested)	—

   For the most certain text-encoder quality, choose Qwen's own Q8_0 (34.8 GB, tested). The import then cuts it to the 50 layers used (about 27 GB written), so that much more space is needed; it has no image part, so the mmproj (F16, 1.2 GB) is added automatically. To generate with reference images, video or audio too, turn on “Include Ref2VA”.
4. Choose where it goes. The “Location” and “Folder name” become the imported model's folder; the downloads are kept inside it until imported. Even on an external disk, the import clones within that disk, so the space isn't doubled.
5. Press “Download and Import”. Download, import and registration in Model Manager run on their own. An interrupted download resumes next time.

Before you press it, the wizard shows the download size, what the import will write, and the free space on the destination disk; with too little room (2 GB is kept in reserve) the button stays off.

Changing the source

Each part's source (a Hugging Face repository) can be changed.

• Known sources: the menu next to the source field offers publishers known to carry that part.
• Listing: the download-arrow button (or Return in the field) reads the first bytes of every file in the source and lists that part's files by what is inside them, not by their names, so each publisher's naming doesn't matter. What was read is kept, so the next time is instant.
• Custom: “Custom…” in the menu takes a repository name or a Hugging Face URL: a repository (https://huggingface.co/owner/name), a folder (…/tree/main/vae), one file (…/blob/main/xxx.gguf, …/resolve/main/xxx.gguf), on main or another branch. Custom places stay in that part's menu and can be removed with “Remove Custom”.
• Remembered: the source chosen is kept per part for next time.

Files the app can't use are still listed, with “(unsupported: reason)”, and can't be picked; see supported formats.

Importing GGUF files you have

With GGUF files already on disk, use Model Manager's “Import GGUF…”.

1. Choose files. “Add GGUF Files…” adds files; “Add from Folder…” adds a folder's (three levels down). Each file is inspected and shown as a DiT, text encoder or vision part. FL2VA and Ref2VA DiTs have the same tensors, so a file whose name contains ref2va is taken as Ref2VA (you can switch it). Missing parts show where to get them, with a “Download…” button.
2. Review. The file used for each part and what is missing are shown; with several files for one part, pick one. “Clone parts from” chooses where the tokenizer, VAEs and configs come from: a model in Model Manager, a folder picked with “Register Folder…”, or the official shared parts fetched with “Download Shared Parts…”.
3. Press “Import”. The model folder is created in ~/Library/Application Support/H3cApp/Imported/ and registered.

After importing

• Model Manager's info button shows what the model holds (each part's format and size, AdaLN form, layers, caches, the import record) and what it can do.
• For the fast M5 mode, build the int8 cache (about 19 GB) with “Build Cache…” in Advanced Settings; GGUF models can have one too.
• M1–M4 run with SSD streaming; GGUF weights are read still quantized and expanded on the GPU, so less is read.

Sources and supported formats

Known sources

These are sorted by reading the files' headers in the download screens. Every source has been checked to make a short video with a typical file around Q4 (see “Combinations checked” below).

Supported formats

• Quantization: Q8_0, Q4_0, Q4_1, Q5_0, Q5_1, Q2_K–Q6_K, F16, BF16, F32. Mixes such as unsloth's “UD-…_XL” work when made only of these.
• Unsupported (listed with the reason): files with IQ types (IQ4_XS, IQ3_XXS, …), I8 and the like; split GGUF files; safetensors DiTs and text encoders (only GGUF can be imported); VAEs in number formats the app can't read (F8, int8, …); text encoders with fewer than 50 layers.
• AdaLN form: DiT GGUFs come with curve-form AdaLN (ComfyUI's “pruned” form) or dense AdaLN. Both work; dense files are about 8 GB larger.
• Text encoder: the engine uses the first 50 layers of Qwen3-VL-32B; a 64-layer file is cut to those 50 when imported.

Combinations checked

For each known source, a DiT and a text encoder from that source at the same quantization (as far as it offers them) made a 3-second 512×512 video with the same prompt and seed using SSD streaming, and the picture and the audio (speech) were checked (October 19, 2026, Apple M5, 24 GB). Sources without a text encoder were paired with unsloth's Q4_K_M; text-encoder-only sources with unsloth's Q4_K DiT.

The image part (mmproj) is only used when generating with reference images, so this check covers loading it.

A plain Q2_K DiT (unsloth's minimax_h3_fl2va_pruned-Q2_K) makes broken videos (melted figures, a grid-like background, humming audio): its block matrices are all Q2_K, 27.7% relative error against Q8_0 (15.6% for Q3_K, 7.4% for Q4_K). Use Q3_K_M or better; H3cApp marks such files with a warning. Q2_K text encoders work, and mixes such as “UD-Q2_K_XL” are untested.

Deleting models and disk space

A GGUF import places files as APFS clones on the same disk, so importing takes almost no space; in exchange, models can share data with each other and with the downloaded originals. Model Manager's “…” → “Delete…” works like this:

• Even when only unregistering, the model's generation caches (int8 cache and the like) are deleted right away (they can be rebuilt).
• With “Also delete the model files”, the model folder goes to the Trash after one more confirmation; the space emptying the Trash will free is shown. Data shared with other models or originals stays, as those still use it.
• Deleting the last model also deletes the downloaded shared parts and GGUF files, and caches no model uses.

License

• The MiniMax H3 model (the official one and GGUF conversions such as unsloth's) is under the MiniMax H3 Community License Agreement; the key points are in Licenses and terms.
• Qwen's text and image parts (Qwen3-VL-32B-Instruct) are under the Apache License 2.0.
• Check each source's own license as well. Read each license before downloading and using them, and follow their terms.

For how it works and the API, see GGUF.md on GitHub.