Qwen Image 2.1 in ComfyUI: Complete Local Setup and Workflow Guide (2026)

The first time I installed Qwen-Image-2.1 in ComfyUI, the workflow loaded fine and then refused to generate anything: Value not in list: unet_name: 'qwen_image_2.1_int8_convrot.safetensors' not in [].

That error cost me 40 minutes, and it had nothing to do with the model. The file had downloaded correctly — into the wrong folder. ComfyUI scans specific directories at startup, and if a 7GB safetensors file lands one level off, it may as well not exist.

This guide is the version of that afternoon I wish I'd had: which variant to download for your card, exactly where each file goes, how to load the official template instead of wiring nodes by hand, and the settings that matter on the first generation. It also covers the case where local isn't the right answer at all — because for a lot of people running 8GB cards, it isn't.

TL;DR

• Qwen Image 2.1 needs three files, not one: diffusion model, text encoder, VAE. Missing any of them throws a model-not-found error the moment you queue.
• Match the variant to your VRAM before you start downloading. BF16 (~14GB) needs 24GB. INT8 (~7.3GB) needs about 12GB. GGUF Q4_K_M (~4–5GB) runs on 8GB.
• GGUF files go in models/unet/, not models/diffusion_models/. This single mistake accounts for most "model doesn't appear in the dropdown" reports.
• Load the official template first. Workflow → Browse Templates → search "Qwen Image 2.1". Wiring the node chain by hand on a first install is how people conclude the model is broken.
• The text encoder loads with CLIPLoader set to type qwen_image. Wrong loader type gives you a silently empty text encoding.
• If you're under 12GB VRAM, expect to spend more time managing memory than generating. A cloud route is cheaper than the upgrade you're about to talk yourself into — more on that at the end.
• For the browser route with no install at all, run Qwen Image 2.1 in the workspace instead of the terminal.

What you need before downloading anything

Three prerequisites, and skipping any of them causes errors that look like model problems:

1. A current ComfyUI build. The Qwen Image 2.1 template ships with recent ComfyUI releases. If you're on a build from before Qwen-Image support landed, the template won't appear in Browse Templates and you'll be wiring nodes manually against a node set that doesn't have them.
2. Disk space. BF16 diffusion model alone is ~14GB; with text encoder, VAE and a GGUF fallback you should budget 25–30GB free.
3. A GPU with a known VRAM number — not "8GB but sometimes 6" from a laptop with shared memory. The variant table below is unforgiving about this.

On the software side you'll also want the Hugging Face CLI, or just use the file browser on the model repo:

pip install -U "huggingface_hub[cli]"

Step 1 — Match the model variant to your VRAM

This is the decision that determines whether the next hour is pleasant or miserable. Qwen Image 2.1 ships in three official precision tiers plus community GGUF quantisations.

Variant	Approx. size	Minimum VRAM	Who it's for
BF16 (full precision)	~14 GB	24 GB	4090/5090-class cards, final-quality work
INT8 convrot	~7.3 GB	12 GB	The default recommendation — best quality per GB
GGUF Q6_K / Q8_0	~6–8 GB	10–12 GB	Near-INT8 quality on mid-range cards
GGUF Q4_K_M	~4–5 GB	8 GB	RTX 3060 12GB, RTX 4060, older cards
GGUF Q2_K / Q3_K_M	~2–3 GB	6–8 GB	Emergency only — visible quality loss

The mistake to avoid: downloading BF16 because it's the "real" model. A 14GB diffusion file plus a text encoder plus VAE overhead does not fit on a 12GB card, and ComfyUI's response to that is not a helpful message — it's a CUDA out-of-memory error mid-generation, after the model has spent two minutes loading.

My recommendation: if you have 12GB or more, take INT8. If you're under 12GB, go straight to the GGUF section and don't download INT8 at all — you'll only be tempted to try it.

Step 2 — Download the three files

Qwen Image 2.1 is distributed by the Qwen team and packaged for ComfyUI in the Comfy-Org repository. The three files live in three subfolders, which is the source of most of the confusion — they're not in one bundle.

# 1. Diffusion model (INT8, recommended)
huggingface-cli download Comfy-Org/Qwen-Image-2.1 \
  split_files/diffusion_models/qwen_image_2.1_int8_convrot.safetensors \
  --local-dir ComfyUI/models/diffusion_models

# 2. Text encoder
huggingface-cli download Comfy-Org/Qwen-Image-2.1 \
  split_files/text_encoders/qwen3vl_8b_int8_convrot.safetensors \
  --local-dir ComfyUI/models/text_encoders

# 3. VAE
huggingface-cli download Comfy-Org/Qwen-Image-2.1 \
  split_files/vae/qwen_image_2.1_vae_bf16.safetensors \
  --local-dir ComfyUI/models/vae

Note what the text encoder is: Qwen3-VL 8B, not a CLIP text encoder. That has two consequences — the file is large (multiple GB), and it needs the matching loader type, which is Step 5's problem.

Step 3 — Put them in the right folders

File type	Folder	Loader node
INT8 / BF16 safetensors	ComfyUI/models/diffusion_models/	Load Diffusion Model
GGUF quantisations	ComfyUI/models/unet/	Unet Loader (GGUF)
Text encoder	ComfyUI/models/text_encoders/	CLIPLoader (type: qwen_image)
VAE	ComfyUI/models/vae/	VAELoader

The GGUF row is the one that breaks installs. ComfyUI-GGUF scans models/unet/, while the standard INT8/BF16 loaders scan models/diffusion_models/. Some newer ComfyUI builds scan both, which is why the same advice appears to work for one person and fail for the next. If your GGUF file doesn't appear in the dropdown, move it to unet/ and restart ComfyUI.

And yes — restart. ComfyUI scans model folders on startup. Dropping files in while it's running does nothing until you reload.

Step 4 — Install ComfyUI-GGUF if you're under 12GB

Two routes, same result:

# Via ComfyUI Manager: search "GGUF" and install

# Or manually:
cd ComfyUI/custom_nodes
git clone https://github.com/city96/ComfyUI-GGUF
cd ComfyUI-GGUF
pip install -r requirements.txt

Then place your chosen quantisation — Q4_K_M is the sane starting point — into ComfyUI/models/unet/ and restart. Ready-made workflows using the UnetLoaderGGUF node are published alongside the GGUF conversions, so you can drag a JSON straight into ComfyUI rather than wiring anything.

Step 5 — Load the official template instead of wiring nodes

With the files in place: Workflow → Browse Templates → search "Qwen Image 2.1."

The template already contains the correct chain: model loader, the Qwen Image text encode node, sampler, VAE decode, save image. Two reasons to use it rather than building your own:

• The node chain for this model is not the same as a generic SDXL or FLUX workflow. The text encoder is an 8B VL model, and the encode node expects it through CLIPLoader with type qwen_image.
• Every custom workflow you build before you've seen one successful generation encodes your misunderstanding of the node graph into hours of debugging.

If the template isn't in the list, your ComfyUI is out of date — go back to the prerequisites rather than trying to assemble it yourself.

Step 6 — First generation settings

Get one image out before tuning anything. Change one variable at a time, in this order:

1. Resolution first. Qwen Image 2.1 handles standard SDXL-class resolutions well (1024×1024, 832×1216, 1216×832). Going straight to 4K-class dimensions on a 12GB card is how you get a memory error that looks like a model bug.

2. Steps and CFG second. The template ships with a working sampler/scheduler pair and a CFG value — the community default range for the Qwen-Image line is roughly 20–30 steps at CFG 2.5–4.0. Start at the template's values, then move in small increments. Doubling CFG does not double prompt adherence; it usually just burns the image.

3. The prompt last. Qwen-Image is unusually good at rendered text, which changes how you prompt: put the literal words in quotes and describe their position ("a shop sign reading 'OPEN 24' above the door"), rather than asking for "a sign with text."

4. The seed, only when you're close. Fixing a seed before the prompt and settings are right produces a series of identically flawed images. For a closer look at how it stacks up against other models, see Krea 2 vs Qwen Image Edit vs Z.

The two workflows worth saving

Text to image is the template as shipped. Save your own copy the moment your prompt and settings are working — template updates overwrite the shipped version, not your saved workflow.

Image edit is the second workflow, and it's where this model earns its install. The edit path takes a source image plus an instruction and changes only the described region. The GGUF repos ship a ready-made image-edit workflow (Qwen_Image_2.1_GGUF_Image_Edit.json) using the same UnetLoaderGGUF node, so the low-VRAM path has parity with the standard one.

For editing, the practical constraint is different from generation: your source image resolution sets the memory ceiling, so a 4000px photo is a bigger problem than a 4000px prompt. Downscale the source to roughly the output resolution you want before feeding it in. If you want to test it without installing anything, the free camera-angle control tool works in the browser.

Turbo: what 4–6 steps actually buys you

Community turbo/Lightning-style LoRAs for the Qwen-Image line cut generation to 4 to 6 steps with a small quality trade. That's the single biggest throughput lever available on consumer hardware — a 4-step run at 1024×1024 finishes in a fraction of a 25-step run, which is the difference between iterating and waiting.

Use it for: prompt exploration, composition drafts, batch variation. Don't use it for: final delivery, dense text rendering, fine detail.

The workflow is the same template with the LoRA loaded into the model input and the step count dropped. If you're still deciding whether the local route is worth the setup time at all, the Qwen-Image-2.1-Turbo breakdown covers what the 8-step version costs and when the full model still wins.

Troubleshooting: the errors you'll actually hit

Symptom	Cause	Fix
Model missing from dropdown	File in the wrong folder, or ComfyUI hasn't rescanned	INT8/BF16 → models/diffusion_models/; GGUF → models/unet/; restart ComfyUI
Value not in list: unet_name … not in []	Loader points at a file that isn't where it looks	Check folder, then re-select the file in the node widget
CUDA out of memory mid-generation	Variant too large, or resolution too high	Drop to a smaller GGUF quant, or reduce resolution first
Garbage / noise output	Wrong CLIPLoader type, or VAE mismatch	CLIPLoader type must be qwen_image; use the 2.1 VAE, not a FLUX or SDXL VAE
Text encode node errors out	Text encoder file missing	Download qwen3vl_8b_int8_convrot.safetensors into models/text_encoders/
Everything works but is very slow	Full-precision model on a small card, spilling to system RAM	Move to INT8 or GGUF; check you're not also loading a second model

That last row catches people who think their GPU is slow. A 14GB model on a 12GB card doesn't fail loudly — it quietly streams weights over PCIe and runs at a tenth of the speed, and the inference is technically correct. If your generation feels wrong by an order of magnitude, check what's actually resident in VRAM.

When local isn't the right answer

Local has three real advantages: no per-image cost, no content filter you didn't set, and full control over the workflow. It also has three costs people underrate:

• Setup time. A first install with a GGUF path is an afternoon. Updates break workflows.
• Throughput. An 8GB card running Q4_K_M is fine for a dozen images and painful for a hundred. If your job is "200 product variants by Friday," local is the wrong tool.
• The hardware trap. Every VRAM problem invites a GPU upgrade. A 24GB card costs more than a decade of cloud generation at the volumes most people actually run.

The honest test: if you generate fewer than ~50 images a day, cloud is cheaper than the electricity and the upgrade. If you generate thousands, or you need a fixed workflow without a rate limit, local wins and the setup cost amortises in a week.

Generate Qwen Image 2.1 without the install

If the point was the image and not the setup, skip the terminal entirely.

Run Qwen Image 2.1 in the browser →

What you get without touching a model folder:

• No download, no VRAM ceiling — the same model on someone else's GPU
• Qwen Image 2.1 alongside Wan, Z-Image and Seedance, so you're not maintaining four installs
• Image edit and text-to-image in one workspace, which is where most of the value of this model sits
• Free allowance to test before deciding whether your workflow justifies a local build

A practical split that works well: prototype prompts in the browser where iteration is free and unlimited by your own hardware, then move the locked workflow to ComfyUI if you need batch volume or no filter. Most people discover they never needed the second half.

The Bottom Line

Qwen Image 2.1 in ComfyUI is a 30-minute job if you match the variant to your VRAM first, put three files in three correct folders, and load the official template instead of wiring nodes.

The failure modes are almost never the model. They're a GGUF file in diffusion_models/, a CLIPLoader set to the wrong type, a missing text encoder, or a BF16 download on a 12GB card that then runs at a tenth of speed through shared memory.

If you're under 12GB and generating a few dozen images at a time, the honest answer is that cloud generation with the same model costs less than the upgrade you'd need to make local pleasant. Test there first — the Qwen Image 2.1 model guide covers what it's good at, and the Z-Image comparison is the better starting point if your priority is speed over text rendering.

Related guides

• Krea 2 vs Qwen Image Edit vs Z-Image: Complete Comparison Guide (2026)
• Wan 3.0 vs Flux 3 Video: Best AI Video Generators Compared 2026
• Z-Image vs Qwen Image: Complete Comparison Guide for AI Creators in 2026

FAQ

What VRAM do I need to run Qwen Image 2.1 in ComfyUI? 24GB for BF16, about 12GB for the INT8 convrot build, 8GB for a GGUF Q4_K_M quantisation. Under 8GB you're limited to Q2_K/Q3_K_M with visible quality loss.

Why doesn't Qwen Image 2.1 show up in the ComfyUI model dropdown? Almost always folder placement. INT8/BF16 files belong in models/diffusion_models/, GGUF files in models/unet/. ComfyUI only scans on startup, so restart after moving files.

What are the three files Qwen Image 2.1 needs? The diffusion model, the Qwen3-VL 8B text encoder, and the Qwen Image 2.1 VAE. All three are in the Comfy-Org/Qwen-Image-2.1 repo under split_files/. Missing any one produces a model-not-found or text-encode error.

Which CLIPLoader type do I use? qwen_image. The text encoder is a Qwen3-VL model, not CLIP — selecting the wrong loader type returns empty conditioning and noise-looking output.

Can I run Qwen Image 2.1 on 8GB of VRAM? Yes, with GGUF Q4_K_M in models/unet/ and the UnetLoaderGGUF node. Expect slower generation and lower resolution ceilings than the INT8 build, and avoid running other GPU applications at the same time.

Do I need the ComfyUI-GGUF custom node? Only for quantised GGUF files. The official INT8 and BF16 safetensors load with ComfyUI's built-in Load Diffusion Model node.

Is Qwen Image 2.1 better at text than other local models? It's the strongest open-weight option for dense rendered text and layouts at this size class, which is why it's worth the 8B text encoder. For pure speed, smaller models still win per image.

Can I use Qwen Image 2.1 commercially? The model is open-weight from the Qwen team, but license terms (including any use restrictions) come from the model card, not from ComfyUI. Read the licence on the repository before commercial deployment.

Is there a way to try it without installing ComfyUI? Yes — generate with Qwen Image 2.1 in the browser and decide whether the local install is worth your afternoon.

References

• Comfy-Org/Qwen-Image-2.1 on Hugging Face — official ComfyUI-packaged weights (diffusion model, text encoder, VAE)
• AlperKTS/Qwen-Image-2.1-GGUF — GGUF quantisations, ready-made text-to-image and edit workflows, folder placement notes
• city96/ComfyUI-GGUF — the GGUF loader node used for low-VRAM installs
• Tech Insider — Set Up Qwen-Image-2.1 in ComfyUI — variant/VRAM table and common setup pitfalls
• Qwen Image 2.1 Edit in ComfyUI — low VRAM GGUF + turbo workflow — 4–6 step turbo workflow walkthrough
• r/comfyui — Qwen Image GGUF testing on 6GB VRAM — community reports on low-VRAM quantisation quality
• Qwen Image 2.1 model guide — capabilities and use cases