MossImage Model Download and Local Setup
The official MOSS-Image weights are Apache-2.0. Download SFT for finished images or Base for fine-tuning, then run them with diffusers, ComfyUI or vLLM-Omni.
Official sources
01 / Choose a checkpoint
Base or SFT?
Both checkpoints share the same architecture and inference pipeline. The difference is post-training, not the interface.
| Base | SFT | |
|---|---|---|
| Purpose | Fine-tuning, LoRA, research | Finished, presentable images |
| Post-training | None; no CFG distillation | Supervised fine-tune of Base |
| Text layout | Raw model behaviour | Curated for clearer text grouping |
| Official examples | All 20 repository examples | No separate gallery published |
| Comfy-Org files | bf16 + int8_convrot | bf16 + int8_convrot |
If you only want to make an image, start with SFT. If you want to train a LoRA, start with Base and keep the text encoder frozen. The official user guide recommends freezing the text encoder for any post-training.
02 / Files
Official weights and repacks
The Hugging Face repositories contain the diffusers bundle. Comfy-Org publishes single-file repacks for ComfyUI.
| Artifact | File | Published size |
|---|---|---|
| Base DiT | moss_image_base_bf16.safetensors | 10.16 GB |
| Base DiT (int8) | moss_image_base_int8_convrot.safetensors | 5.41 GB |
| SFT DiT | moss_image_sft_bf16.safetensors | 10.16 GB |
| SFT DiT (int8) | moss_image_sft_int8_convrot.safetensors | 5.41 GB |
| Text encoder | qwen3.5_9b_bf16.safetensors | 19.31 GB |
| Text encoder (int8) | qwen3.5_9b_int8_convrot.safetensors | 9.75 GB |
| Text encoder (W4A8) | qwen3.5_9b_w4a8_gptq.safetensors | 7.34 GB |
| VAE | flux2-vae_small.safetensors | 0.25 GB |
Derived disk footprints: BF16 DiT + BF16 text encoder + small VAE ≈ 29.7 GB; INT8 DiT + INT8 text encoder ≈ 15.4 GB; INT8 DiT + W4A8 text encoder ≈ 13.0 GB. The diffusers bundle totals about 27.2 GB because its text-encoder shards are packaged differently from the Comfy single file.
03 / Hardware
What the official docs say about memory
There is no published minimum VRAM table. The numbers below are the official operating profiles and derived file sizes, not benchmarks.
Do not treat these as minimum requirements
The official Gradio app selects a 16 GB, 24 GB or 48 GB profile. The 16 GB and 24 GB profiles use model CPU offload; only the 48 GB profile keeps the model fully resident. Official docs do not guarantee BF16 operation on 16 GB.
The BF16 diffusers checkpoint is about 27.2 GB on disk. System RAM and disk headroom scale with the offload mode. For a practical local install, budget for the weights plus a working ComfyUI environment and temporary output files.
04 / Python
Run it with diffusers
This is the official Python API, trimmed to a 1024×1024 run. The README uses 1456×1456 for its refrigerator example; either is valid.
import torch
from diffusers import DiffusionPipeline
pipe = DiffusionPipeline.from_pretrained(
"OpenMOSS-Team/MOSS-Image-Base",
custom_pipeline="pipeline_moss_image",
trust_remote_code=True,
torch_dtype={"default": torch.bfloat16, "vae": torch.float32},
)
pipe.scheduler = type(pipe.scheduler).from_config(pipe.scheduler.config)
pipe.to("cuda")
image = pipe(
"A minimalist travel poster with a cream background, a blue mountain "
"illustration, and the title EXPLORE at the top.",
height=1024,
width=1024,
num_inference_steps=50,
guidance_scale=3.0,
uncond_skip_layers=[22],
generator=torch.Generator("cpu").manual_seed(42),
).images[0]
image.save("moss-image.png")05 / ComfyUI
Run it in ComfyUI
The repository ships a native node and official workflow JSON, including Base and API-format variants.
Follow our ComfyUI workflow guide for the node install, the loader path, the official sampler settings and the documented errors. The source README is here.
06 / Serving
Run it with vLLM-Omni
For an OpenAI-compatible HTTP endpoint, use the official vLLM-Omni image. The SFT checkpoint is supported by this recipe.
# CUDA 13 image (driver R580+). For CUDA 12.9 use vllm/vllm-omni:mosimage-cu129.
export IMAGE=vllm/vllm-omni:mosimage
export MODEL=OpenMOSS-Team/MOSS-Image-SFT
docker pull "$IMAGE"
docker run --rm --name moss-image \
--gpus 'device=0' --ipc=host \
-p 8000:8000 \
-v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
-e HF_TOKEN \
"$IMAGE" \
vllm serve "$MODEL" --omni --enforce-eager --port 8000Send flow_shift: 5.0 explicitly to match the checkpoint scheduler. If the host driver is older than R580, use the CUDA 12.9 image (mosimage-cu129).
07 / Troubleshooting
Documented errors
These are the failure modes covered by the official repository and loader code.
- Invalid image dimensions — width and height must be positive multiples of 16.
- GPU memory exhausted — use a smaller image, the sequential fallback, or component offload.
- ComfyUI cannot find the model — the loader expects a local directory containing transformer/, text_encoder/, tokenizer/ and vae/; it does not download a Hub repo id.
- Wrong text encoder — MOSS-Image requires the Qwen3.5-9B encoder from the same bundle.
- Text is truncated — the ComfyUI text encoder is capped at 4096 tokens.
- ComfyUI output differs from Python — the ComfyUI scheduler does not use the standalone pipeline's training-grid snapping; matching seeds do not guarantee identical images.
08 / License
Apache-2.0, with upstream notices
The MOSS-Image weights and bundled inference code are Apache-2.0. The Qwen text encoder and FLUX.2 VAE retain their own upstream licenses. Commercial use is permitted under Apache-2.0; keep the license and attribution notices when you redistribute the weights.
09 / FAQ
Download FAQ
Is MOSS-Image free to download?
Yes. The Base and SFT weights are published under Apache-2.0. The bundled Qwen text encoder and FLUX.2 VAE keep their own upstream licenses, so check those notices before redistribution.
Which version should I download, Base or SFT?
Download SFT if you want finished images with cleaner text grouping. Download Base if you plan to fine-tune, train a LoRA, or study the raw model: it has no post-training or CFG distillation.
How much VRAM do I need?
The official project does not publish a minimum VRAM table. The BF16 checkpoint is about 27.2 GB on disk (derived from the published file sizes), and the official Gradio app keeps the model fully resident only at 40 GiB or more; below that it uses component offload. Use the 16/24/48 GB profiles as an operating hint, not a guarantee.
Can I run it in ComfyUI?
Yes. The repository ships a native ComfyUI node and two example workflow files. Our ComfyUI guide walks through the install and includes the official JSON downloads.
Why do my dimensions fail?
MOSS-Image requires width and height to be positive multiples of 16. The pipeline also expects the text encoder and VAE from the same bundle; mixing a different Qwen or VAE checkpoint fails inside the loader.
Next