Hugging Face Publishing

mlxgen prepare creates a local MLX-Gen model package and writes a README.md model card into it. The generated card cites the source model, mflux, MLX-Gen, the exact mlx-gen version used to generate the card, the quantization policy, the source license/access policy when MLX-Gen can infer it, and the default contributor attribution to @lpalbou.

Generated cards include python -m pip install -U mlx-gen in the usage block so Hugging Face readers can copy and paste a complete baseline command without needing uv. Repository development and release workflows still use uv.

Use mlxgen prepare before upload whenever you want to publish a quantized MLX-Gen package. mlxgen download only fills the local Hugging Face cache and does not create an uploadable package.

Bonsai Image is an exception: Prism's Bonsai repositories are already packed MLX artifacts, so MLX-Gen supports download/generate rather than preparing or republishing a derivative package.

Prepare A Model Package

mlxgen prepare \
  --model Qwen/Qwen-Image-Edit-2511 \
  --path ./models/qwen-image-edit-2511-4bit \
  --quantize 4

The local package contains the MLX-Gen saved-weight layout plus the generated README.md model card. The card includes a Generated with mlx-gen <version> line so published quantized checkpoints can be traced back to the package version that created them.

The package can then be uploaded to Hugging Face:

huggingface-cli upload AbstractFramework/qwen-image-edit-2511-4bit ./models/qwen-image-edit-2511-4bit .

The generated usage block uses the default AbstractFramework/<repo-name> repository id. SeedVR2 cards use mlxgen upscale because SeedVR2 is an image super-resolution command, not a mlxgen generate route.

Collections

Model-card metadata does not add a model to a Hugging Face collection. Use the Hugging Face UI or huggingface_hub.HfApi.add_collection_item after the model repository exists.

Use the collection slug from the Hugging Face collection URL:

from huggingface_hub import HfApi

HfApi().add_collection_item(
    collection_slug="<collection-slug>",
    item_id="AbstractFramework/qwen-image-edit-2511-4bit",
    item_type="model",
    exists_ok=True,
)

Compatibility Wording

Generated cards describe model-specific low-bit policies. Qwen and ERNIE q4 checkpoints use mixed q4/q8 wording to preserve generative quality. Wan q8 checkpoints use mixed q8/BF16 wording because MLX-Gen keeps Wan conditioning/output projection linears, the VAE, and the UMT5 text encoder at BF16. SeedVR2 q4/q8 cards describe image super-resolution packages and the mlxgen upscale command. Other q8 checkpoints use the standard MLX-Gen/mflux q8 wording. Bonsai pre-packed repositories are not generated by mlxgen prepare.

See Quantization for the current Qwen, ERNIE, SeedVR2, Wan, and Bonsai low-bit policies.

License And Access Wording

Generated cards include license metadata for supported families where the source license is known:

• Qwen, Z-Image, ERNIE Image Turbo, and FLUX.2 Klein 4B derivatives are marked license: apache-2.0.
• FLUX.2 Klein 9B and FLUX.2 Klein base-9B derivatives are marked license: other with license_name: flux-non-commercial-license, source license links, and gated-access prompts.

When publishing a gated derivative, also configure the Hugging Face repository settings so the repository itself is gated. Model-card metadata alone does not enforce access control.