Custom NCNN Model Support#

Upscayl's upscaling backend (upscayl-bin) is a Vulkan-backed ncnn binary. It accepts any compatible ncnn model as a .bin/.param pair — enabling users to swap in third-party or self-converted models alongside the seven built-in models 1.

Adding Custom Models#

The official workflow is documented in docs/Guide.md (available since v2.5):

1. Create a folder (conventionally named models) and place your .bin and .param files in it.
2. In Upscayl → Settings → Add Custom Models, click Select Folder and point to that directory.
3. In the Upscayl tab, pick the custom model from the upscaling-type dropdown.

The folder must contain only .param/.bin files; any other file type causes an "Invalid Folder" dialog and the scan is aborted 2.

Model Discovery#

electron/utils/get-models.ts handles discovery. It reads the directory with fs.readdirSync and collects the basename (stem without extension) of every .param or .bin file (case-insensitive). Duplicate stems are deduplicated so each model appears once in the list 3.

The selected folder path is persisted to localStorage under "customModelsFolderPath" and loaded back into the runtime variable savedCustomModelsPath on startup.

Converting PyTorch Models to NCNN#

The Model Conversion Guide describes converting .pth PyTorch models to ncnn format using chaiNNer:

1. Install the PyTorch and NCNN dependencies inside chaiNNer.
2. Load this .chn pipeline, select the source .pth model, and run it.
3. chaiNNer produces a .bin and a .param. Manually edit the .param file: change every "input" value in column 2 and column 3 to "data" 4.
4. Copy both files into your models folder and follow the "Adding Custom Models" steps above.

Only PyTorch models are guaranteed to work. ONNX conversion is possible (using onnxsim) but frequently fails 5.

Pre-converted community models are available from the Upscayl Custom Models Repository.

Scale Inference from Filenames#

Upscayl does not read metadata from the model file to determine its output scale. Instead, common/check-model-scale.ts infers scale purely from the filename:

Name your custom model files accordingly. For example, my-model-x2.bin/.param will be treated as a 2× model. Mismatch between actual model output and inferred scale will cause incorrect behaviour 6.

Since v2.8, Upscayl emulates unsupported scales by downscaling the 4× output. Custom models from the repository (e.g., realesr-animevideov3-x2, realesr-animevideov3-x3) provide native non-4× scale support 7.

How the Backend Receives the Model#

When launching upscayl-bin, the Electron layer passes two distinct flags 8:

• -m <modelsPath> — directory containing the model files. For custom models this resolves to savedCustomModelsPath; for built-ins it uses the bundled path 9.
• -n <modelName> — the model stem (filename without extension) selected by the user.

The binary then loads <modelsPath>/<modelName>.param and <modelsPath>/<modelName>.bin for inference.

Hardware Considerations (Vulkan Backend)#

upscayl-bin uses ncnn's Vulkan backend — it does not use CUDA, Metal, or vendor-specific runtimes. This means custom models run through the same Vulkan pipeline on all GPUs.

Intel integrated graphics (Iris Xe and similar): No XMX/AI-accelerator path is used. Inference runs entirely through Vulkan compute shaders. Known issues include vkQueueSubmit failed -4 (VK_ERROR_DEVICE_LOST) — especially on the second or subsequent images — and screen flickering on affected systems 10. Mitigations: reduce tile size, update GPU drivers, or set the GPU ID explicitly to the preferred Vulkan device 11.

Multi-GPU systems: upscayl-bin enumerates all Vulkan physical devices at startup and defaults to device [0]. Use the GPU ID setting (Settings → GPU ID, passed as -g) to force a specific device. The device list is visible in the Upscayl logs on every run 11.

Vulkan driver bug flags: The backend startup log includes fields like bugbilz, bugsbn1, etc. Elevated values signal known driver bugs on that device and may correlate with inference failures 11.

Key Source Files#