How to Use MOSS-Image in ComfyUI

MOSS-Image is a 5-billion-parameter open-source text-to-image model released by OpenMOSS on October 16, 2026. Its standout feature is readable Chinese and English text rendered directly inside generated images — something most AI image models still struggle with. And from day one, it shipped with native ComfyUI support.

Setup time depends on your connection, hardware, and ComfyUI experience. This guide walks through every required step. By the end, you will have a working setup, a test image, and a plan for switching between the Base and SFT checkpoints.

Choose your installation path

MOSS-Image offers two ways to run inside ComfyUI. Pick one and stick with it — their loader nodes are not interchangeable, and mixing them can silently change the sampling behavior.

Path	Best for	Model format
Native ComfyUI	New installations, current ComfyUI builds	Separate diffusion model, text encoder, and VAE files
HF-directory plugin	Existing plugin workflows, loading a local Diffusers directory	A complete directory with transformer/, text_encoder/, tokenizer/, and vae/

If you only want to test prompts without managing model files or a GPU, use the browser-based generator at mossimage.run. The rest of this guide assumes you want the model running on your own hardware.

Native ComfyUI setup (recommended)

Native MOSS-Image support was merged into ComfyUI on October 16, 2026. You need a build containing commit e087d8f6 or later. Release v0.41.3 does not include this support — update if you are on that version.

Step 1: Download the model components. Go to the Comfy-Org MOSS-Image repository on Hugging Face and download the three component files. Place them in these folders:

Component	Folder
Diffusion model	`ComfyUI/models/diffusion_models/`
Text encoder	`ComfyUI/models/text_encoders/`
VAE	`ComfyUI/models/vae/`

Step 2: Import the native workflow. Download the native workflow JSON and drag it into your ComfyUI canvas. The graph uses Load Diffusion Model, CLIP Loader with type set to moss_image, Load VAE, and the MOSS-Image Layout Prompt node. Do not replace individual nodes with equivalents from another workflow — import the complete graph.

Step 3: Run a first test. Set the canvas to 1024 × 1024, use a fixed seed, and keep the workflow's included sampler settings. Queue one image before adding any extensions or changing precision. If the image generates, the setup is correct. Save the working graph and record the model filenames.

The model defaults to shift 5. If you manually adjust shift, the official guide specifies ModelSamplingAuraFlow with multiplier 1 — using other values can produce unexpected output.

HF-directory plugin setup (alternative)

Use this path when you already have plugin workflows or want to load a complete local Diffusers directory.

Step 1: Download the model. Clone either the Base or SFT repository from Hugging Face without flattening its structure. You should end up with a directory containing four subdirectories:

your-model-directory/
├── transformer/
├── text_encoder/
├── tokenizer/
└── vae/

Step 2: Install the plugin. From an OpenMOSS MOSS-Image checkout, copy the node directory into your ComfyUI custom nodes folder:

cp -r comfyui/moss-image/ /path/to/ComfyUI/custom_nodes/moss-image/

Alternatively, run the repository installer:

python comfyui/install.py --comfy-root /path/to/ComfyUI

Restart ComfyUI after installation. If MOSSImageHFLoader does not appear in your node list, check the startup log for import errors.

Step 3: Set model_path. In the MOSSImageHFLoader node, point model_path at the directory containing the four component folders. Use an absolute path — relative paths depend on how ComfyUI was launched and can break silently:

/home/user/models/MOSS-Image-SFT

Do not point at a single safetensors file. The loader needs the directory structure intact.

Step 4: Import the matching workflow. Download the official HF-directory workflow JSON. It ships with 50 steps, CFG 3, shift 5, Euler sampler, and sgm_uniform scheduler. Run it unchanged for the first test.

Understand the two workflows: they are not interchangeable

A common mistake is importing one workflow and swapping only the loader node. The official ComfyUI guide explicitly warns against this: the native path uses a different timestep multiplier, and the sampling graphs differ. If you move from the plugin workflow to native, import a native workflow — do not replace MOSSImageHFLoader with Load Diffusion Model and expect identical results.

The same rule applies when switching between Base and SFT. Keep the workflow type consistent. Point the loader at the correct checkpoint directory, but do not change the graph architecture.

Manage memory: change one variable at a time

MOSS-Image is a 5B model, modest by current standards, but runtime memory depends on several interacting variables: model format, precision, offloading, resolution, and which components stay resident. Download size is not a VRAM requirement.

For a 1024 × 1024 canvas at default settings, start with the official workflow and monitor peak memory during the first run. If you hit an out-of-memory error:

Situation	Try this
Tight VRAM	Use an official quantized native model, lower the canvas size, and enable supported CPU or sequential offloading
More VRAM available	Use the BF16 native model components when your hardware and ComfyUI build support them
Frequent OOM	Reduce dimensions and confirm that two copies of the model or text encoder are not loaded by separate nodes

In the HF-directory node, weight_dtype offers default, BF16, FP32, and several FP8 modes. It does not expose an INT8 or FP16 option. text_device offers the default device or CPU. The plugin loads the VAE in FP32 regardless of other settings.

Switch between Base and SFT

MOSS-Image ships two checkpoints:

Base: The foundation checkpoint. Apache 2.0. Best for evaluation, LoRA training, and custom post-training. Requires careful inference settings.
SFT: Supervised fine-tuned from Base. Same license. Better text grouping and more organized layouts in published comparisons. Ready for direct image generation.

For native ComfyUI, select the matching Base or SFT diffusion model while keeping compatible text-encoder and VAE files in their documented folders. For the plugin path, point model_path at the complete Base or SFT Diffusers directory. Always run a fixed-seed test after switching.

If you are not sure which to use: start with SFT. It is the checkpoint designed for prompt-to-image creation. The hosted studio at mossimage.run uses the SFT endpoint through fal.ai, so testing prompts online before committing to a local setup is the fastest way to evaluate.

Troubleshooting common issues

"MOSSImageHFLoader does not appear." Confirm the plugin is linked or copied to ComfyUI/custom_nodes/moss-image/, then fully restart a current ComfyUI build and inspect the startup log.

"model_path is invalid." Point at the directory containing the four component folders — not at a single file.

"The native workflow shows unknown nodes." Update ComfyUI to a build with native MOSS-Image support and install that build's current dependencies.

"The output differs from the hosted studio." The online studio uses the hosted SFT endpoint with 50 inference steps. Provider precision and runtime details are not exposed. The plugin scheduler does not use the standalone pipeline's training-grid snapping, so matching a seed and visible settings does not guarantee a pixel-identical result.