ComfyUI-VOSR2 Introduction
ComfyUI-VOSR2 brings the VOSR 2.0 image super-resolution model into ComfyUI. Super-resolution means enlarging an image while reconstructing detail, rather than simply stretching its existing pixels.
You can use it to turn a small image into a larger version for further editing or presentation. VOSR 2.0 focuses on restoring fine structures, including the kinds of edges and small details found in buildings, landscapes, faces, and text-rich images.
The extension provides two nodes:
- VOSR 2.0 Model Loader loads the model and its required components.
- VOSR 2.0 Upscale processes your image using your chosen enlargement, color, and tiling settings.
VOSR 2.0 is a vision-only, one-step model with a 1.4-billion-parameter image-restoration network. In practical terms:
- Vision-only: your input image guides restoration; you do not need a text prompt.
- One-step: the main generative restoration happens in one step, rather than through a long sampling sequence.
- Generative: the model reconstructs plausible detail. Treat the output as a restoration, not proof of what was present in the original image.
Other useful features include automatic model downloads, image-batch support, repeatable noise seeds, color alignment, and separate tiling controls for restoration and image decoding.
Important: For output images larger than 512 pixels on either side, enable restoration tiling. The node defaults leave tiling disabled.
This is a standalone community integration maintained by the author. It is not part of the upstream VOSR repository.
- ComfyUI-VOSR2 repository
- Upstream VOSR repository
- VOSR model files on Hugging Face
- Interactive VOSR 2.0 visual comparisons
How ComfyUI-VOSR2 Works
Think of VOSR 2.0 as a restoration team with three matched tools: one studies the image, one reconstructs detail, and one translates between ordinary pixels and the model’s internal representation.
1. The vision encoder studies your image
The DINOv2-L vision encoder extracts visual features from the input. These features describe patterns and structures that help guide restoration.
DINOv2 was trained to learn visual features without manually supplied labels. In this extension, it provides image-based guidance—not a separate text-prompting system.
2. The VAE provides an internal image representation
The Qwen-Image 2D VAE converts between pixels and a compact representation called a latent. You can think of a latent as a working format that the restoration network can process.
VOSR uses an image-only, two-dimensional version of the Qwen-Image VAE. The upstream project provides this version to avoid the unnecessary overhead of the original video-oriented design.
3. The restoration network reconstructs detail
The LightningDiT-based network performs the one-step restoration, guided by your input image and its visual features.
Your seed controls the latent noise used during this process. Keeping the seed unchanged helps you compare settings without also changing this source of variation.
“One-step” does not mean the entire workflow is instantaneous: loading, feature extraction, VAE processing, color alignment, and any tiled processing still take time.
4. Tiling handles larger images
Instead of processing a large image as one canvas, tiling processes smaller, overlapping sections.
Imagine restoring a mural one section at a time, with shared borders between neighboring sections. Those shared borders help the sections join more smoothly.
The extension exposes two separate tile controls:
tile_sizecontrols tiles for the restoration network. This matters for quality above the model’s native training size and also helps manage memory.vae_tile_sizecontrols tiles for VAE decoding. This helps reduce memory pressure when turning the restored representation back into a large image.
These controls solve different problems. Enabling restoration tiling does not automatically enable VAE tiling.
5. Color alignment adjusts the final result
Optional color alignment compares the restored image with a bicubic enlargement of the input—a conventional resize used as a color reference.
This gives you a way to bring the output’s overall appearance closer to the source while retaining restored detail.
ComfyUI-VOSR2 Features
Both nodes appear under image/upscaling/VOSR2 in ComfyUI.
VOSR 2.0 Model Loader
The loader returns a VOSR2_MODEL object, which connects to the upscale node’s model input.
Keeping model loading separate from upscaling avoids rebuilding several gigabytes of model weights for every queued image.
| Input | Default | Available settings | What it means for you |
|---|---|---|---|
model | VOSR2 | Bundle folders under models/vosr2/ | Selects the matched restoration model, VAE, and vision encoder. Leave this on VOSR2 for normal use. |
dtype | default | default, fp16, bf16 | Controls numerical precision for the restoration network and vision encoder. Reduced precision can save GPU memory. |
Precision and memory: fp16 or bf16 roughly halves the memory used by the restoration network and vision encoder compared with full precision. This does not halve the entire workflow’s memory use: the VAE always runs in fp32.
If you are unsure which precision to choose, begin with default.
Automatic model downloads
The first execution of the loader downloads missing components from the pinned CSWRY/VOSR Hugging Face repository.
- The complete bundle is approximately 7 GB.
- Existing files are detected and reused.
- Downloads happen when the loader executes—not when the extension imports or the workflow is validated.
- Only the pinned model repository is contacted for model retrieval.
- The extension does not use
torch.hub. - The downloaded model configuration is checked against the expected VOSR 2.0 architecture before construction.
Your first run therefore includes download and preparation time. Later runs reuse the downloaded files.
VOSR 2.0 Upscale
This node accepts a single ComfyUI IMAGE or an image batch.
| Input | Default | Range or options | Purpose |
|---|---|---|---|
model | — | VOSR2_MODEL | Connect the model loader’s output here. |
image | — | IMAGE | Your source image or image batch. |
upscale | 4 | At least 1; no hard upper cap | Sets the output enlargement multiplier. |
seed | 42 | Nonnegative integer | Controls latent noise. |
color_alignment | wavelet | wavelet, adain, none | Chooses post-processing for color consistency. |
tile_size | 0 | 0–4096, increments of 64 | Restoration tile size in pixels. 0 disables tiling. |
tile_overlap | 32 | 0–512, increments of 8 | Overlap between restoration tiles. |
vae_tile_size | 0 | 0–8192, increments of 64 | VAE decode tile size in pixels. 0 decodes the whole image at once. |
vae_tile_overlap | 32 | 0–512, increments of 8 | Overlap between VAE tiles. |
Choosing an enlargement factor
upscale is an exact output multiplier. For example:
| Input image | upscale | Output image |
|---|---|---|
| 128 × 128 | 4 | 512 × 512 |
| 512 × 512 | 2 | 1024 × 1024 |
| 512 × 512 | 4 | 2048 × 2048 |
| 640 × 360 | 4 | 2560 × 1440 |
VOSR 2.0 was trained on degradations up to 16×, but that is not a guarantee of reliable 16× enlargement. Quality beyond approximately 4× depends on the image and output resolution.
For a first comparison, try 2× or 4× before attempting more aggressive enlargement.
Choosing color alignment
| Setting | Description | Suggested use |
|---|---|---|
wavelet | Wavelet-based color alignment against the bicubic reference. | Start here; it is the default. |
adain | An alternative alignment method based on matching color statistics. | Compare it with wavelet when the overall color or tone needs adjustment. |
none | Disables color-alignment post-processing. | Inspect the model’s result without this correction. |
For a useful comparison, keep your image, seed, enlargement, and tile settings fixed, and change only color_alignment.
Tiling and overlap
VOSR 2.0 was trained natively at sizes up to 512 pixels. According to the author’s guidance, outputs larger than 512 pixels on either side require restoration tiling to avoid quality degradation.
Start with:
tile_size = 512for outputs larger than 512 pixels on either side.vae_tile_size = 1024for outputs much larger than approximately 1024 pixels, to reduce the risk of running out of GPU memory.
Overlap gives neighboring tiles shared image content. More overlap means more repeated processing, so it can increase processing time. The recommended starting overlaps are larger than the node defaults:
tile_overlap = 64vae_tile_overlap = 128
The author has not published a measured tile-size/VRAM table. These values are starting points, not guarantees that a particular GPU can process every image.
Batch processing and seeds
For a batch, item i uses seed + i, starting with item 0.
With a base seed of 42:
- First image: seed
42 - Second image: seed
43 - Third image: seed
44
To reproduce a batch item individually, use that item’s corresponding seed and the same remaining settings.
ComfyUI-managed model memory
The extension integrates with ComfyUI’s model loading and offloading system through ModelPatcher. This allows ComfyUI to manage model memory rather than having the extension handle it entirely independently.
It does not eliminate GPU memory limits; large outputs can still require tiling.
Using ComfyUI-VOSR2
Start with the example workflow
The simplest starting point is the bundled workflow:
Download the VOSR 2.0 example workflow
Drag the JSON file onto the ComfyUI canvas. It includes ready-made node graphs with the loader, upscale node, and tiling presets connected.
VOSR 2.0 example workflow in ComfyUI
A hosted example is also available:
- Open the shared RunComfy workflow (https://www.runcomfy.com/comfyui-workflows/my-workflows?shared_workflow=764db3d9-242d-87a7-4157-3cd95923fea7)
Set up the nodes manually
- Add VOSR 2.0 Model Loader.
- Leave
modelonVOSR2and begin withdtype = default. - Add VOSR 2.0 Upscale.
- Connect the loader’s model output to the upscale node’s
modelinput. - Connect your source image to the upscale node’s
imageinput. - Choose
upscale, then calculate the expected output dimensions. - Set
tile_size = 512if either output dimension exceeds 512 pixels. - For larger outputs, use
vae_tile_size = 1024as a starting point. - Connect the resulting image to your preferred preview or save node, then run the workflow.
Recommended general-purpose settings
For outputs larger than 512 pixels, the author recommends this starting configuration:
| Parameter | Value |
|---|---|
upscale | 4 |
seed | 42 |
color_alignment | wavelet |
tile_size | 512 |
tile_overlap | 64 |
vae_tile_size | 1024 |
vae_tile_overlap | 128 |
These are recommended settings, not the node’s defaults. Both tile-size defaults are 0.
For an output that stays at or below 512 × 512, tiling is not needed.
ComfyUI-VOSR2 Models
Supported bundle: VOSR2
The documented supported bundle is VOSR2, containing a fixed set of components:
| Component | Role | Compatibility requirement |
|---|---|---|
| VOSR 2.0 LightningDiT checkpoint | Performs one-step generative restoration. | Must use its matched VAE and vision encoder. |
| Qwen-Image 2D VAE | Translates between images and the model’s internal representation. | Must be the specific VAE used for this model. |
| DINOv2-L / ViT-L/14 encoder | Extracts visual features to guide restoration. | Must use the expected checkpoint and weight format. |
args.json | Describes the model configuration. | Must match the fixed VOSR 2.0 architecture. |
These are parts of one model bundle, not interchangeable style models.
You cannot substitute an unrelated VAE or another DINO model. The broader DINOv2 project offers other sizes and specialized models, but those are not documented as compatible replacements here.
Other upstream VOSR models
The upstream repository also lists:
VOSR_0.5B_ms— 0.5B multi-step model.VOSR_0.5B_os— 0.5B one-step model.VOSR_1.4B_ms— 1.4B multi-step model.VOSR_1.4B_os— 1.4B one-step model.
These belong to the broader upstream project. Their availability upstream does not establish support in ComfyUI-VOSR2.
Similarly, upstream multi-step controls such as sampling steps, cfg_scale, and weak_cond_strength_aelq are not inputs on the documented ComfyUI upscale node.
Bundle location and file reference
Normally, you do not need to manage these files yourself. The loader places the bundle under:
ComfyUI/models/vosr2/VOSR2/
├── args.json
├── checkpoints/
│ └── ema_model.safetensors
├── Qwen-Image-vae-2d/
│ ├── config.json
│ └── diffusion_pytorch_model.safetensors
└── dinov2_vitl14.safetensors
For checking missing files or preparing an offline workflow:
| Required component | Source |
|---|---|
| Model configuration | VOSR2/args.json |
| Restoration checkpoint | ema_model.safetensors |
| VAE configuration | Qwen-Image-vae-2d/config.json |
| VAE weights | diffusion_pytorch_model.safetensors |
| Original DINOv2-L weights | dinov2_vitl14_pretrain.pth |
The loader automatically converts the original DINOv2 .pth file to the required dinov2_vitl14.safetensors format. Simply renaming the file is not a conversion.
Do not substitute the Hugging Face Transformers facebook/dinov2-large weights: their internal weight names differ from the architecture used by this extension.
Additional bundle folders containing an args.json can appear in the model dropdown, but discovery does not guarantee compatibility. Only VOSR2 is automatically downloaded.
What’s New with ComfyUI-VOSR2
The supplied documentation does not contain a complete extension changelog. The following milestones and status notes are explicitly documented.
August 22, 2026 — upstream VOSR 2.0 release
The upstream project released VOSR 2.0 as a one-step, 1.4B, vision-only model with improved fine-structure restoration.
For you, the main change is a restoration model focused on preserving small structures without requiring text prompts or a multi-step sampling setup.
See the interactive visual comparisons to judge the changes on example images.
Extension version 0.2.0 — first-run remote download
The author identifies 0.2.0 as the release that introduced first-run remote model downloads.
This reduces manual model-file preparation: missing components are retrieved when the loader first executes.
The supplied README also reports that registry scans flagged releases from 0.2.0 onward, causing some registry-based tools to serve 0.1.0. This is a documented distribution-status note, not a model-quality warning. Consult the extension repository for updated status.
Documented implementation status
The author describes the package as an in-progress v1. Implemented capabilities include:
- Model discovery and architecture validation.
- Automatic first-run downloads.
- Bundled implementations of the required model architectures.
- ComfyUI-managed model loading and offloading.
- Untiled and tiled restoration and VAE processing.
- Per-item seeded batches.
wavelet,adain, andnonecolor alignment.- A drag-and-drop example workflow.
Automated Linux/CPU checks verified package loading and valid registration of both nodes using Python 3.10, PyTorch 2.10, and ComfyUI 0.35.0.
Those checks did not execute model loading and GPU restoration. The author also lists numerical comparison against upstream, measured VRAM presets, GPU execution in automated tests, and macOS/Windows test coverage as unfinished.
Updates to unrelated DINOv2 research models are not ComfyUI-VOSR2 releases and do not add supported model choices to this extension.
Troubleshooting ComfyUI-VOSR2
The first run is taking much longer than expected
The loader may be downloading and preparing approximately 7 GB of model files.
- Check the ComfyUI console for download progress or an error.
- Confirm that your computer can access CSWRY/VOSR on Hugging Face.
- Check that sufficient disk space is available for the bundle.
- Allow downloading and preparation to finish before judging normal processing time.
Files already present are reused on subsequent runs.
Large outputs look worse than expected
Check the output dimensions, not only the source image size.
- Multiply the input width and height by
upscale. - If either result exceeds 512 pixels, set
tile_size = 512. - Start with
tile_overlap = 64. - Run again with the same seed.
- If enlargement is greater than approximately 4×, compare a lower factor.
For example, a 256 × 256 source enlarged 4× becomes 1024 × 1024 and needs restoration tiling.
Processing fails with an out-of-memory error
An out-of-memory error means the GPU cannot hold everything required for the operation.
- Enable restoration tiling with
tile_size = 512. - Enable VAE tiling with
vae_tile_size = 1024, especially for outputs well above 1024 pixels. - Try
fp16orbf16in the loader where supported by your hardware. - If necessary, test one image at a time or reduce the enlargement factor.
Remember that the VAE remains in fp32. Reduced loader precision does not reduce every part of the workflow’s memory use.
The output’s colors have shifted
- Fix the seed so you can make a fair comparison.
- Try
color_alignment = wavelet. - Compare with
adain. - Use
noneto inspect the result without color correction. - Choose the option that best suits your source image and intended look.
The loader reports an incompatible checkpoint
The loader validates args.json against the expected VOSR 2.0 architecture.
- Return the
modelselection toVOSR2. - Check that all components belong to the documented VOSR2 bundle.
- Remove unrelated VAE or vision-encoder substitutions from consideration.
- If you are using a custom bundle, verify its architecture rather than assuming that appearing in the dropdown means it is supported.
A manually supplied DINOv2 file does not load
- Confirm that the source is the original
dinov2_vitl14_pretrain.pthlisted above. - Do not use Transformers-format
facebook/dinov2-largeweights. - Confirm that the required converted file is named
dinov2_vitl14.safetensorsand is inside the VOSR2 bundle folder. - Use the loader’s automatic retrieval and conversion when possible.
For manual conversion details, see the author’s repository documentation.
A batch image differs from an individual run
- Find the image’s zero-based position in the batch.
- Add that position to the batch’s base seed.
- Use the resulting seed for the individual run.
- Keep precision, color alignment, enlargement, and tiling unchanged.
For example, the third image in a batch with base seed 42 uses seed 44.
Frequently asked questions
Do I need a prompt?
No. The documented nodes use image-based guidance and do not expose a text-prompt input.
Can I adjust sampling steps or CFG?
Not through these nodes. This integration exposes the one-step VOSR 2.0 workflow, not the upstream multi-step controls.
Is 4× the maximum enlargement?
No. There is no hard upper cap, but quality beyond approximately 4× is not guaranteed.
Can I replace the VAE with one from another workflow?
No. The restoration checkpoint requires its matched Qwen-Image 2D VAE and DINOv2-L encoder.
Does one-step processing mean low memory use?
Not necessarily. Model weights, image size, VAE decoding, precision, and tile settings all affect memory requirements.
What GPU memory capacity is required?
The supplied documentation does not provide a measured minimum or a reliable VRAM table.
Can I work offline?
Existing local bundle files are reused without downloading them again. Prepare the complete, correctly formatted bundle before working offline.
Will it recover every letter or facial detail accurately?
Do not assume that it will. Inspect important details carefully: generative restoration can produce plausible detail without guaranteeing that it matches the original scene.
Learn More about ComfyUI-VOSR2
Practical resources
- Bundled starter workflow — the most direct way to explore the nodes and their tiling presets.
- Workflow screenshot — a visual reference for the ComfyUI node layout.
- Shared RunComfy workflow (https://www.runcomfy.com/comfyui-workflows/my-workflows?shared_workflow=764db3d9-242d-87a7-4157-3cd95923fea7) — a hosted workflow example.
- VOSR 2.0 project page — interactive before-and-after comparisons. Drag the sliders to inspect restoration on different image subjects.
- ComfyUI-VOSR2 repository — the author’s documentation, example files, and package-status information.
Background and model references
- Upstream VOSR repository — broader documentation about the restoration framework and its model family.
- VOSR paper — a technical explanation of the research behind the model.
- VOSR model repository — model assets and their associated terms.
- DINOv2 overview (https://ai.facebook.com/blog/dino-v2-computer-vision-self-supervised-learning/) — background on the visual-feature technology used for conditioning.
- ScreenSR benchmark — the upstream project’s real-world paired super-resolution benchmark, covering varied scenes and multilingual text. It is not required for ordinary upscaling.
ComfyUI-VOSR2 Licensing and Acknowledgements
The node package uses the Apache License 2.0. See LICENSE for its terms.
Model weights are downloaded separately and may have their own terms, including those associated with DINOv2 and the Qwen-Image VAE. Review the relevant model-hosting pages before commercial use or redistribution. Benchmark data and other external assets may also have separate conditions.
This extension builds on:
- VOSR / VOSR 2.0 — the upstream image-restoration research and models.
- DINOv2 — Meta AI’s visual-feature encoder.
- Qwen-Image VAE — the image-representation component supplied by the Qwen team and adapted upstream for 2D image processing.
- LightningDiT — the foundation for the restoration network.
- The author’s ComfyUI integration — the nodes, model-bundle handling, tiling controls, and example workflows documented here.
