QwenImage Layered V2 Loader

Qwen-Image-Layered is the December 2025 model that decomposes a flat image into a recursive stack of RGBA layers - Alibaba's answer to "the Photoshop layers that raster images never had." ComfyUI already has native support for it (the Comfy-Org port runs the V2 LoRA through UNETLoader → LoraLoaderModelOnly → ModelSamplingAuraFlow → KSampler), and that chain is fine. What it has never had is a mask input. This whole pack exists to bolt brush control onto the official DiffSynth pipeline, and this node is its front door: it assembles the V1 base model, the V2 control LoRA, the official text encoder and the official layered VAE into a single QWEN_LAYERED_V2_PIPELINE that you hand to QwenImage Layered V2 Decompose.

Be clear-eyed about what you're buying. The README calls this a prototype in its first line. It's a 20B stack running through DiffSynth rather than ComfyUI's native sampler, it's slow, and its brush control is soft conditioning rather than a hard mask. If you just want layered outputs with zero fuss, use the native port. If you want to steer which layer gets pulled out with a brush, this is one of the few places that lets you try.

What it actually loads

The node resolves model files the same way every ComfyUI loader does - through folder_paths, so you pick short filenames and never type an absolute path. From ComfyUI/models/diffusion_models it takes the V1 base, qwen_image_layered_control_bf16.safetensors; from ComfyUI/models/loras the V2 LoRA, Qwen-Image-Layered-Control-V2.safetensors. Both are resolved to local paths and handed to DiffSynth as ModelConfig(path=...), so they're never re-downloaded.

The other two weights are the ones that bite. DiffSynth needs the official Qwen/Qwen-Image text encoder and tokenizer, plus the official Qwen/Qwen-Image-Layered VAE, cached locally:

ComfyUI/models/Qwen/Qwen-Image/text_encoder/model*.safetensors
ComfyUI/models/Qwen/Qwen-Image/tokenizer/*
ComfyUI/models/Qwen/Qwen-Image-Layered/vae/diffusion_pytorch_model.safetensors

This is where people get burned. ComfyUI's qwen_2.5_vl_7b_fp8_scaled.safetensors - the FP8 repack you almost certainly already have - is not recognized by DiffSynth's QwenImagePipeline, and neither is ComfyUI's qwen_image_layered_vae.safetensors. The VAE parameter naming doesn't even line up. So a working ComfyUI Qwen install does not mean this node will run.

The inputs that matter

• allow_official_download (default False). With it off, the loader errors out the moment the official text encoder/tokenizer/VAE cache is missing - it will not silently download. Flip it on to have DiffSynth fetch them from download_source (modelscope or huggingface).
• vram_mode (low / medium / high) and vram_margin_gb. Low and medium lean on fp8 offload to CPU/disk to squeeze a 20B pipeline into consumer VRAM; high keeps bf16 on the GPU and is for cards with headroom. vram_margin_gb (default 1.0) tells the pipeline how much headroom to leave. This is a VRAM-hungry model - community reports on the native port range from "runs extremely slowly" on decent cards to outright disappointment on 8GB - so don't expect miracles on a 3050.
• device (default "cuda"). Leave it alone unless you know you're CPU-only.

Output is a single pipeline socket (type QWEN_LAYERED_V2_PIPELINE), which is not an image - wire it straight into the Decompose node.

Installing it

ComfyUI Manager (search "ComfyUI-QwenImageLayered"), or the manual route:

cd ComfyUI/custom_nodes
git clone https://github.com/bambom/ComfyUI-QwenImageLayered
# restart ComfyUI

Then the one that trips people up: the pack's requirements.txt only lists diffsynth, numpy, pillow - it does not install DiffSynth-Studio for you. You must add it to ComfyUI's own Python environment:

git clone https://github.com/modelscope/DiffSynth-Studio.git
cd DiffSynth-Studio
pip install -e .

If it's missing, the node raises a runtime error that literally prints those commands back at you. The install isn't always smooth - DiffSynth's other tooling has a reputation for error-chasing - so budget some time here. Once everything is cached, you can set DIFFSYNTH_SKIP_DOWNLOAD=True to stop it poking the network, and DIFFSYNTH_MODEL_BASE_PATH to point the cache elsewhere.

If the load fails, 90% of the time it's one of the official files missing, not your weights. Re-read the error: it tells you exactly which cache path it expected.