Wan2.1-VAE-upscale2x

Wan2.1-VAE-upscale2x

Replaces the Wan2.1 VAE decoder with one that upscales images 2x and removes speckle and grain artifacts, for ComfyUI and diffusers. For people who generate images with Wan or Qwen models.

Made by spacepxl on Hugging Face. These notes are Mindket's, written from its model page and model card; the model's own files and license are on Hugging Face.

About

What it is: Only the decoder of the Wan2.1 VAE was retrained here, and it now doubles the image size as part of decoding. Its main job is to get rid of the speckles, polka dots and grain that the original decoder leaves in Wan images. It also helps in hires fix workflows, since the extra resolution costs almost no extra compute. The first release is trained on images only.

Who it suits: It suits people who generate images with Wan or Qwen models and want cleaner, larger output, in ComfyUI or in Python code.

Industry | Who uses it | How they use it | Example
Image generation | ComfyUI users | Decode latents with the 2x decoder instead of upscaling afterwards | Replacing a separate upscaler step in a hires fix workflow
Digital art | Creators of realistic images | Get cleaner skin and hair detail from a decoder | Decoding a generated portrait and comparing it with the original decoder
Software | Developers using diffusers | Swap the VAE in a Wan pipeline for this one | Loading it with the Wan autoencoder class
Research | VAE researchers | Study a decoder-only finetune built on perceptual losses | Reading the card's notes on LPIPS, FDL and GAN loss

If your images are anime, line art or text, you can skip it, since the card says it was trained almost only on real images.

Where to use it:

• ComfyUI, with the author's ComfyUI-VAE-Utils custom nodes
• Python code that uses the diffusers library
• Windows, macOS or Linux with Python, for downloading the files

Use case | Who | What they get back
Clean decoding | Image generators | Pictures without the speckle and grain of the original decoder
Hires fix | ComfyUI users | A 2x larger image straight from the decoder
Original size output | Anyone who wants the old resolution | A slight blur and downsample gives a cleaner image at the original size

How to set it up:

• Python and the Hugging Face hub package
• For ComfyUI, the ComfyUI-VAE-Utils custom nodes from the author's GitHub page
• For code, torch and diffusers with the AutoencoderKLWan class

1. Install the Hugging Face hub package.
2. Download the model files.
3. In ComfyUI, install the custom nodes that load and decode latents.
4. In Python, load the VAE from its subfolder with diffusers, as shown below.

pip install -U huggingface_hub
hf download spacepxl/Wan2.1-VAE-upscale2x

How to use it: In ComfyUI, the custom nodes load the VAE and decode latents in a way that matches the native nodes. Wan wrapper latents also work once they are de-normalized with the right wrapper node. In diffusers, decode the latents and rearrange the 12 output channels with a pixel shuffle.

import torch
import torch.nn.functional as F
from diffusers import AutoencoderKLWan

vae = AutoencoderKLWan.from_pretrained("spacepxl/Wan2.1-VAE-upscale2x", subfolder="diffusers/Wan2.1_VAE_upscale2x_imageonly_real_v1")
decoder_out = vae.decode(latents, return_dict=False)[0] # [B, 12, F, H, W]
decoded_video = F.pixel_shuffle(decoder_out.movedim(2, 1), upscale_factor=2).movedim(1, 2) # pixel shuffle needs [..., C, H, W] format
# or just use decoder_out.squeeze(2) for images to convert BCFHW to BCHW

Tool | What it does
AutoencoderKLWan | Loads the VAE in diffusers
vae.decode | Turns latents into a 12-channel output
F.pixel_shuffle | Rearranges those channels into an image at twice the size
ComfyUI-VAE-Utils | Custom nodes for loading and decoding latents in ComfyUI

Example: You decode the latents of a generated portrait with this decoder. The picture comes out at twice the resolution, with fewer speckles in skin and hair. For the original size, blur it slightly and scale it back down.

For newcomers and experts: A VAE converts between pictures and the compact latent form that image models work in. Its decoder turns a latent back into a picture. This decoder also makes the picture twice as large. A good first try is the ComfyUI route with the custom nodes.

Under the hood, the encoder stays unchanged and frozen, so the latent space is preserved, and only the decoder is trained. The last Conv3d layer of the decoder was swapped so it outputs 12 channels instead of 3, and a pixel shuffle turns them into a larger image. Training combines L1, LPIPS, FDL and GAN losses, and the final run took about 40 hours on a single 5090.

Latents from a Wan or Qwen model
Retrained decoder with 12 output channels
Pixel shuffle
Image at twice the resolution

Good to know:

• The author shares no metrics, because tuning was done by eye for human perceptual quality.
• Decoded images may show slight color shifts and can look overly sharp. Color matching and blur can correct that.
• The first version is image-only, and it is compatible with both Wan and Qwen because they share a latent space. A video version is planned.
• License: Apache 2.0
• Cost to run: none named
• Data it reaches: none named beyond the latents and files you give it, run locally
• Not for: anime, line art or text, since the training data was almost all real images

On Hugging Face, 13 November 2026

• Library: diffusers
• Formats: Safetensors
• Downloads in the last 30 days: 15,963
• Likes: 242
• License: apache-2.0
• Based on: Wan-AI/Wan2.1-T2V-14B
• Tags: diffusers, safetensors

Links

• Model: https://huggingface.co/spacepxl/Wan2.1-VAE-upscale2x
• Files: https://huggingface.co/spacepxl/Wan2.1-VAE-upscale2x/tree/main

Get the model

Download its files with Hugging Face's command line:

pip install -U huggingface_hub
hf download spacepxl/Wan2.1-VAE-upscale2x

Then follow the usage in its model card. Nothing in this kit runs by itself.