waifu2x-ncnn-vulkan: a portable Vulkan upscaler for Intel, AMD, NVIDIA and Apple Silicon GPUs

What waifu2x-ncnn-vulkan solves, and who it is for

The original waifu2x was a Caffe model, and the practical way to run it on a GPU was waifu2x-caffe, which expects CUDA and cuDNN. That is fine on an NVIDIA desktop. It is useless on a laptop with integrated Intel graphics, on an AMD card, or on an Apple Silicon Mac. waifu2x-ncnn-vulkan exists to remove that dependency: it reimplements the converter on top of Tencent's ncnn inference framework and talks to the GPU through Vulkan, the cross-vendor graphics API. The README states the package includes all the binaries and models required and is portable, so no CUDA or Caffe runtime environment is needed.

The audience is therefore anyone who wants waifu2x's particular behaviour, denoising plus 2x or 4x upscaling of anime-style line art and illustrations, on hardware that the Caffe build does not cover. That includes Linux users, Mac users, and people on Windows machines with AMD or Intel GPUs. It is a command-line tool. There is no window, no drag-and-drop, and the repository lists no homepage, so the release page is the distribution channel.

How the ncnn and Vulkan pipeline is put together

The architecture is a three-stage pipeline, and the CLI exposes the stage boundaries directly. The README describes the load:proc:save thread count as covering image decoding, waifu2x upscaling, and image encoding. Each stage gets its own thread count, which is why the default is 1:2:2 rather than a single number. Decoding one image is cheap, the neural network pass is the expensive part, and encoding is somewhere in between. If the GPU is idle while the CPU decodes, the ratio is wrong for your workload.

The inference itself is ncnn, and the model files live in the models directory of the repository, with models-cunet as the default model path. Tile size is the other lever. The README says a smaller tile reduces GPU memory usage and that the default selects automatically, which means the tool decides how much of the image to push through the network at once. That decision is a memory and speed trade-off, not a quality one: tiling splits the image spatially, so a tile that is too small costs you repeated work at the seams, while a tile that is too large can exhaust VRAM on a modest card.

The remaining pieces are the encoders and decoders, which the README credits to libwebp, libjpeg-turbo, libpng and zlib-ng. That is why the input and output format list is jpg, png and webp rather than anything broader.

Installing waifu2x-ncnn-vulkan and running a first upscale

There is no package manager step. The README points at the GitHub releases page for Windows, Linux and macOS executables for Intel, AMD, NVIDIA and Apple Silicon GPUs, and the release list shows dated tags such as 20250915. Download the archive for your platform, unpack it, and keep the models directory next to the binary, because the default model path is relative.

The shortest real command is the one the README gives as its example. It reads input.jpg, writes output.png, applies noise level 2 and scales by 2:

waifu2x-ncnn-vulkan.exe -i input.jpg -o output.png -n 2 -s 2

On Linux or macOS the binary has no .exe suffix, but the flags are identical. Expect a new PNG next to wherever you pointed -o. If the run fails immediately, the README's first suggestion is to upgrade your GPU driver, with links for Intel, AMD and NVIDIA.

Both -i and -o accept a directory, which is the batch mode. Point them at folders and every supported image inside is processed:

waifu2x-ncnn-vulkan.exe -i input.jpg -o output.png -n 2 -s 2 -t 200

If the process dies on a large image, or the machine becomes unresponsive, the tile size is the first thing to change. The README documents -t as accepting values of 32 or greater, with 0 meaning automatic.

For a machine with more than one GPU, -g takes a device id, and the README notes that -1 selects the CPU, 0,1,2 selects multiple GPUs, and that tile-size can be written as 0,0,0 for multi-GPU. The thread ratio can be given per device too, for example 1:2,2,2:2.

Where waifu2x-ncnn-vulkan is the wrong tool

The model is trained on anime-style artwork, and the README's own sample section is explicit about the comparison it invites: a plain ImageMagick resize, an ImageMagick Lanczos resize, and the waifu2x result at noise=2 scale=2. On photographic material, a neural upscaler that has learned illustration line art can invent texture that was never in the source. If your input is a photo, a conventional resampler is the safer default.

The second limitation is that this is a batch CLI, not a service. There is no documented API, no queue, no job status endpoint, and no resume behaviour. The README does not document rollback or partial-output recovery, so a run interrupted halfway leaves you to work out which files in the output directory are complete. If you need to drive upscaling from an application, you are wrapping a subprocess.

The third is memory. The README's own speed table shows the cunet model at 4000x4000 input consuming roughly 2.4 GB of GPU memory at block size 400 and dropping to around 213 MB at block size 100. A 4x or 8x scale on a large source, or a high thread count, can put a card with modest VRAM under pressure. The README warns that larger load:proc:save values may increase GPU usage and consume more GPU memory.

Finally, the speed picture is not a clean win. In the README's comparison table against waifu2x-caffe-cui, the ncnn build is faster at small and medium sizes and uses substantially less memory, but at 4000x4000 to 8000x8000 with the upconv_7_anime_style_art_rgb model, the Caffe build records 9.24 to 11.16 seconds against 11.16 to 12.07 seconds for the ncnn build. The memory advantage holds; the speed advantage does not, at the largest size tested.

waifu2x-ncnn-vulkan versus the Caffe and CUDA builds

The obvious alternative is waifu2x-caffe, which the README links as part of the original waifu2x project family. The difference is the runtime, not the model family. waifu2x-caffe runs the network through Caffe with CUDA and cuDNN, so it is locked to NVIDIA hardware and to a working CUDA installation. waifu2x-ncnn-vulkan runs the same kind of network through ncnn on Vulkan, which is why the same download works on Intel, AMD, NVIDIA and Apple Silicon.

That portability is bought with the numbers in the README's tables. The Caffe build holds a narrow lead on the largest images in the upconv_7 model, while the ncnn build wins clearly on GPU memory across the board, dropping to a few hundred megabytes at small block sizes where the Caffe build stays above a gigabyte. If you are on NVIDIA hardware, have CUDA set up, and upscale very large images in bulk, the Caffe path is still defensible. If you are anywhere else, it is not an option at all.

A second alternative worth naming is doing nothing: the README's sample images exist precisely to show a plain 200 percent resize and a Lanczos resize next to the waifu2x output. For some images the difference is cosmetic, and the tool costs GPU time you may not need to spend.

Building from source, maintenance, and the MIT licence

The README documents a source build for people who cannot use the prebuilt archives. On macOS it asks you to install the Vulkan SDK from LunarG first. Then the project is cloned with its submodules, which matters because ncnn and the image codecs are submodules rather than vendored copies:

git clone https://github.com/nihui/waifu2x-ncnn-vulkan.git
cd waifu2x-ncnn-vulkan
git submodule update --init --recursive

The build is CMake, run against the src directory rather than the repository root:

mkdir build
cd build
cmake ../src
cmake --build . -j 4

On macOS the README notes a -DUSE_STATIC_MOLTENVK=ON option to avoid linking the Vulkan loader library. That is the only build flag the README documents, and it does not describe a Windows or Linux source build in detail beyond these steps.

Maintenance looks healthy on the evidence available: the repository is not archived, the last push was on 2026-04-13, and the releases list shows dated tags through 2025. The project is MIT licensed, which is permissive and imposes no copyleft obligation on your own code. It does not resolve the licences of what it links: ncnn, libwebp, libjpeg-turbo, libpng and zlib-ng are separate projects with their own terms, and the README credits them rather than restating their licences. If you redistribute a build, check those upstream licences yourself; this is not legal advice.

Editorial conclusion

Adopt waifu2x-ncnn-vulkan if you want waifu2x denoising and upscaling on a machine whose GPU vendor is not NVIDIA, or if you refuse to install a CUDA and cuDNN stack. Skip it if your images are photographs, if you need batch orchestration beyond a directory argument, or if you need a documented API rather than a command line. Before committing, run one image at your target scale with the default tile size and watch GPU memory, then re-run with a smaller -t value to confirm the tile actually fits your card. The repository is MIT licensed and the last push was on 2026-04-13, so pin the release tag you download rather than tracking the branch.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nihui/waifu2x-ncnn-vulkan on GitHub
4. README
5. Releases