ComfyUI-PiD

Compact ComfyUI nodes for NVIDIA PiD / PixelDiT using ComfyUI-native Comfy-Org/PixelDiT model loading.

<img width="1058" height="604" alt="ComfyUI-PiD workflow screenshot" src="https://github.com/user-attachments/assets/cc5a9da3-94c6-4546-9574-c8387d5dffdb" /> <img width="4096" height="2048" alt="ComfyUI-PiD example output" src="https://github.com/user-attachments/assets/7ccd55ee-e571-4996-9c9c-4b5cecbb4418" />

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.