ComfyUI-PiD
ComfyUI custom nodes for NVIDIA PiD pixel diffusion decoding with VRAM offload support.
Nodes (10)
Local Qwen captions so PiD knows what it's looking at
Swap your VAE Decode for a pixel-diffusion decoder
The empty latent that already knows your backbone
The last hop from PiD samples to a saveable image
The sampler that saves the exact moment PiD wants
The staging node that loads PiD's heavy models once
Where the pixel diffusion actually runs
One prompt, two outputs, zero setup
NVIDIA's pixel-diffusion decoder as a tiled 2x–8x upscaler
VAE-free text-to-image straight in RGB space
ComfyUI-PiD
Compact ComfyUI nodes for NVIDIA PiD / PixelDiT using ComfyUI-native Comfy-Org/PixelDiT model loading.
PiD is a latent-conditioned pixel diffusion decoder/upscaler:
LATENT + caption + sigma -> PiD -> IMAGE
Install
cd ComfyUI/custom_nodes
git clone https://github.com/Merserk/ComfyUI-PiD.git
cd ComfyUI-PiD
python -m pip install -r requirements.txt
Restart ComfyUI.
Requirements: recent ComfyUI with native PixelDiT/PiD support, Python >=3.10, NVIDIA CUDA GPU recommended. PiD v1.5 requires ComfyUI 0.28.0 or newer.
Models
Most nodes can download required files automatically when auto_download=true.
| Use | Source | Local folder |
| --- | --- | --- |
| PiD diffusion + Gemma text encoder | Comfy-Org/PixelDiT | ComfyUI/models/diffusion_models/nvidia_pid/ and ComfyUI/models/text_encoders/nvidia_pid/ |
| PixelDiT text-to-image generation | Comfy-Org/PixelDiT | ComfyUI/models/diffusion_models/nvidia_pid/ and ComfyUI/models/text_encoders/nvidia_pid/ |
| Caption Creator | Qwen/Qwen3.5-0.8B | ComfyUI/models/text_encoders/nvidia_pid/qwen35_caption/ |
| Upscale VAEs | Flux/Z-Image, Flux2, SD3 VAE files | ComfyUI/models/vae/nvidia_pid/ |
PiD v1 and v1.5 files are downloaded from diffusion_models/. They are stored in the flat local ComfyUI/models/diffusion_models/nvidia_pid/ folder; v1.5 filenames already include their version.
Use model_precision=bf16 for best quality. PiD v1 fp8 is available only for Flux1-family 2k/2kto4k and Flux2-family 2k; Flux2 2kto4k, SD3, SDXL, and Qwen-Image must use bf16. PiD v1.5 supports bf16 and int8; its INT8 ConvRot diffusion model uses the FP8 Gemma text encoder. Unsupported combinations produce an error and never fall back to another version.
PiD selectors are compatibility-aware in the ComfyUI interface. Changing version, backbone, or pid_ckpt_type immediately removes unsupported downstream choices and normalizes an invalid current value to a supported one. For example, selecting v1.5 removes 2k, SD3/SDXL, and fp8, while enabling int8. PiD Empty Latent Image similarly hides SDXL and Qwen backbones in 2k mode. Backend validation remains active for API prompts and older workflows.
Nodes
| Node | Output | Purpose |
| --- | --- | --- |
| PiD Decode | IMAGE | One-node PiD decode from latent + caption + sigma. |
| PiD Text Prompt | text, caption | One prompt for normal text encoding and PiD caption input. |
| PiD Caption Creator | text, caption | Creates a caption from an input image with local Qwen. |
| PiD Empty Latent Image | LATENT | Backbone-aware empty latent with correct channels/downscale. |
| PiD KSampler Capture | final_latent, pid_latent, pid_sigma | KSampler-compatible sampler that captures the PiD latent and sigma. |
| PiD Prepare | PID_PREP | Moves/validates latent data and resolves PiD model assets. |
| PiD Sample | PID_SAMPLES | Runs native PiD sampling. |
| PiD Finalize | IMAGE | Converts PiD samples to a ComfyUI image. |
| PiD Upscale | IMAGE | Image-only tiled PiD upscaler with 2x/4x/6x/8x output. |
| PixelDiT Generate | IMAGE | VAE-free 1024-class text-to-image generation with native PixelDiT. |
Recommended PiD sampling: pid_steps=4, cfg_scale=1.0, scale=0 or 4.
PixelDiT Generate
PixelDiT Generate creates images directly in RGB pixel space. It does not load or run a traditional VAE. Connect the text output from PiD Text Prompt, select a precision and resolution, then connect the generated IMAGE to Save Image.
| Setting | Values / behavior |
| --- | --- |
| model_precision | bf16 uses the BF16 diffusion model and Gemma encoder; fp8 uses the MXFP8 diffusion model and FP8 Gemma encoder. |
| resolution | Eight approximately one-megapixel presets from 1024x1024 through portrait, widescreen, and ultrawide formats. |
| steps | Default 30, matching the official ComfyUI PixelDiT workflow. |
| cfg_scale | Default 4.0. |
| sampler_name / scheduler | Default er_sde / simple. |
| negative_prompt | Defaults to NVIDIA/ComfyUI's recommended quality exclusions. |
Generation models are downloaded automatically when enabled:
pixeldit_1300m_1024px_bf16.safetensors
pixeldit_1300m_1024px_mxfp8.safetensors
PixelDiT generation requires ComfyUI 0.28.0 or newer. The NVIDIA model weights use the NSCLv1 license and are limited to non-commercial research/evaluation use.
Supported Backbones
| Backbone value | PiD family | Versions | Checkpoints | Latent | PiD Upscale |
| --- | --- | --- | --- | --- | --- |
| zimage | Flux1 | v1, v1.5 | v1: 2k/2kto4k; v1.5: 2kto4k | 16ch / 8x | yes |
| zimage-turbo | Flux1 | v1, v1.5 | v1: 2k/2kto4k; v1.5: 2kto4k | 16ch / 8x | yes |
| flux | Flux1 | v1, v1.5 | v1: 2k/2kto4k; v1.5: 2kto4k | 16ch / 8x | yes |
| flux2 | Flux2 | v1, v1.5 | v1: 2k/2kto4k; v1.5: 2kto4k | 128ch / 16x | yes |
| flux2-klein-4b | Flux2 | v1, v1.5 | v1: 2k/2kto4k; v1.5: 2kto4k | 128ch / 16x | yes |
| flux2-klein-9b | Flux2 | v1, v1.5 | v1: 2k/2kto4k; v1.5: 2kto4k | 128ch / 16x | yes |
| sd3 | SD3 | v1 | 2k, 2kto4k | 16ch / 8x | yes |
| sdxl | SDXL | v1 | 2kto4k only | 4ch / 8x | no |
| qwenimage | Qwen-Image | v1, v1.5 | 2kto4k only | 16ch / 8x | no |
| qwenimage-2512 | Qwen-Image | v1, v1.5 | 2kto4k only | 16ch / 8x | no |
dinov2 and siglip are not supported by the native Comfy-Org PiD model set.
Output Size Guide
Released PiD checkpoints use native 4x scale.
PiD v1 supports the rows shown below. PiD v1.5 provides only the 2kto4k profile.
| pid_ckpt_type | Base latent/image size | Final PiD output | Valid base presets |
| --- | --- | --- | --- |
| 2k | 512-class | base × 4, e.g. 512x512 -> 2048x2048 | 512x512, 576x432, 432x576, 624x416, 416x624, 672x384, 384x672, 784x336, 336x784 |
| 2kto4k | 1024-class | base × 4, e.g. 1024x1024 -> 4096x4096 | 1024x1024, 1024x768, 768x1024, 1008x672, 672x1008, 1024x576, 576x1024, 1008x432, 432x1008 |
Latent size depends on backbone downscale. Example: Flux2 1024x1024 uses a 128 × 64 × 64 latent.
PiD Upscale
PiD Upscale accepts IMAGE and returns IMAGE. It is separate from latent decode: the node cuts the image into tiles, encodes each tile with the matching VAE, runs native 4-step PiD, blends tiles, then resizes to the selected final factor.
| Setting | Values / behavior |
| --- | --- |
| pid_ckpt_type | 2k uses 512px tiles; 2kto4k uses 1024px tiles. |
| version | v1 supports 2k and 2kto4k; v1.5 supports only 2kto4k and only Flux1/Flux2-family backbones. |
| backbone | zimage, zimage-turbo, flux, flux2, flux2-klein-4b, flux2-klein-9b, sd3. |
| model_precision | v1 uses bf16/supported fp8; v1.5 uses bf16 or INT8 ConvRot. Use bf16 for best quality. |
| upscale_factor | Final output size: 2x, 4x, 6x, or 8x. |
| strength | PiD detail regeneration sigma, 0.0 to 1.0; default 0.4. |
| caption | Optional string input; connect PiD Caption Creator or PiD Text Prompt. |
| Profile | Tile size | Overlap | Small-image prepass |
| --- | ---: | ---: | ---: |
| 2k | 512 | 64 | Resize long edge to 512, PiD once, then tiled upscale. |
| 2kto4k | 1024 | 128 | Resize long edge to 1024, PiD once, then tiled upscale. |
Upscale VAEs are required because image tiles must be encoded into each backbone latent format:
| Backbone family | Accepted VAE names |
| --- | --- |
| Flux1 / Z-Image | ae.safetensors |
| Flux2 / Flux2-Klein | flux2_ae.safetensors, flux2-vae.safetensors |
| SD3 | sd3_vae.safetensors, diffusion_pytorch_model.safetensors |
Final upscale size is always based on the original input image: width × factor, height × factor. SDXL and Qwen-Image are not available in PiD Upscale because this implementation only maps image VAEs for Flux1/Z-Image, Flux2/Flux2-Klein, and SD3.
Recommended Capture Settings
| Backbone | LDM steps | Capture step | Sampler / scheduler |
| --- | ---: | ---: | --- |
| flux, sd3 | 28 | 24 | euler / flowmatch_euler_discrete |
| sdxl | 30 | 26 | euler / normal |
| flux2 | 50 | 46 | euler / flowmatch_euler_discrete |
| flux2-klein-4b, flux2-klein-9b | 4 | 4 | euler / flowmatch_euler_discrete |
| qwenimage, qwenimage-2512 | 50 | 44 | euler / flowmatch_euler_discrete |
| zimage | 50 | 46 | euler / flowmatch_euler_discrete, flowmatch_shift=3.0 |
| zimage-turbo | 9 | 9 | euler / flowmatch_euler_discrete, flowmatch_shift=3.0 |
Main Workflows
Text-to-image / generation
PiD Text Prompt -> normal text encode + PiD caption
PiD Empty Latent Image -> model sampler
PiD KSampler Capture pid_latent + pid_sigma -> PiD Prepare
PiD Prepare -> PiD Sample -> PiD Finalize -> Save Image
VAE-free PixelDiT generation
PiD Text Prompt -> PixelDiT Generate -> Save Image
Direct decode
LATENT + caption + sigma -> PiD Decode -> Save Image
Image-to-image clean decode
Load Image -> Resize -> VAE Encode -> PiD Prepare -> PiD Sample -> PiD Finalize -> Save Image
Tiled upscale
Load Image -> PiD Caption Creator -> PiD Upscale -> Save Image
Example Workflows
Included in example_workflows/:
pid_flux_complete.json
pid_flux2_complete.json
pid_flux2_klein_4b_complete.json
pid_flux2_klein_9b_complete.json
pid_qwenimage_complete.json
pid_qwenimage_2512_complete.json
pid_sd3_complete.json
pid_sdxl_complete.json
pid_zimage_complete.json
pid_zimage_turbo_complete.json
pid_image_to_image_2k_complete.json
pid_image_to_image_2kto4k_complete.json
pid_upscale_complete.json
pid_pixeldit_generate_complete.json
License
The ComfyUI-PiD node code is MIT licensed. PixelDiT/PiD model weights are distributed separately under NVIDIA's NSCLv1 license.