NCNN Executable

Use the portable Real-ESRGAN-ncnn-vulkan executable without Python or CUDA

Overview

Real-ESRGAN provides portable executable files powered by NCNN and Vulkan. These executables work on Intel/AMD/Nvidia GPUs without requiring Python, PyTorch, or CUDA installation.

The NCNN executable is ideal for users who want a simple, portable solution without setting up a Python environment.

Download Executables

Windows

Download for Windows

Linux

Download for Ubuntu/Linux

MacOS

Download for MacOS

Direct Download Links

# Windows
https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesrgan-ncnn-vulkan-20220424-windows.zip

# Linux
https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesrgan-ncnn-vulkan-20220424-ubuntu.zip

# MacOS
https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesrgan-ncnn-vulkan-20220424-macos.zip

Quick Start

1. Download and Extract

   Download the appropriate executable for your platform and extract the archive.

2. Run Basic Command

   Windows

   realesrgan-ncnn-vulkan.exe -i input.jpg -o output.png
   

   Linux/MacOS

   ./realesrgan-ncnn-vulkan -i input.jpg -o output.png
   
3. Check Output

   The enhanced image is saved as output.png with 4x upscaling by default.

Command-Line Reference

Basic Syntax

Usage: realesrgan-ncnn-vulkan -i infile -o outfile [options]...

Arguments

-h · flag

Show help message

-i input-path · string · required

Input image path (jpg/png/webp) or directory

Examples:

• Single file: -i input.jpg
• Directory: -i input_folder

-o output-path · string · required

Output image path (jpg/png/webp) or directory

Examples:

• Single file: -o output.png
• Directory: -o output_folder

-s scale · integer · default: "4"

Upscale ratio: 2, 3, or 4

Example: -s 2 for 2x upscaling

-t tile-size · integer · default: "0"

Tile size (>=32 or 0=auto)

• 0: Auto tile size
• >=32: Manual tile size
• Format for multi-GPU: 0,0,0

Use tiling for large images or limited VRAM.

-m model-path · string · default: "models"

Folder path to pre-trained models

-n model-name · string · default: "realesr-animevideov3"

Model name to use. Options:

• realesr-animevideov3 (default)
• realesrgan-x4plus
• realesrgan-x4plus-anime
• realesrnet-x4plus

-g gpu-id · string · default: "auto"

GPU device to use

• auto: Automatic selection
• Single GPU: -g 0, -g 1, etc.
• Multi-GPU: -g 0,1,2

-j load:proc:save · string · default: "1:2:2"

Thread count for load/proc/save

• Default: 1:2:2
• Multi-GPU: 1:2,2,2:2

-x · flag

Enable TTA (Test-Time Augmentation) mode

Improves quality but increases processing time.

-f format · string · default: "ext/png"

Output image format: jpg, png, or webp

• Default: same as input or PNG

-v · flag

Verbose output (show detailed information)

Available Models

realesr-animevideov3

Default model - Optimized for anime videos and images

# Windows
realesrgan-ncnn-vulkan.exe -i input.jpg -o output.png -n realesr-animevideov3

# Linux/MacOS
./realesrgan-ncnn-vulkan -i input.jpg -o output.png -n realesr-animevideov3

• Size: XS (~8MB)
• Best for: Anime images and video frames
• Speed: Fast

realesrgan-x4plus

General purpose model

# Windows
realesrgan-ncnn-vulkan.exe -i input.jpg -o output.png -n realesrgan-x4plus

# Linux/MacOS
./realesrgan-ncnn-vulkan -i input.jpg -o output.png -n realesrgan-x4plus

• Size: ~64MB
• Best for: Real-world photos, general images
• Speed: Medium

realesrgan-x4plus-anime

Anime-optimized model

# Windows
realesrgan-ncnn-vulkan.exe -i input.jpg -o output.png -n realesrgan-x4plus-anime

# Linux/MacOS
./realesrgan-ncnn-vulkan -i input.jpg -o output.png -n realesrgan-x4plus-anime

• Size: ~17MB
• Best for: Anime illustrations
• Speed: Medium-Fast

realesrnet-x4plus

ESRGAN without GAN (smoother results)

# Windows
realesrgan-ncnn-vulkan.exe -i input.jpg -o output.png -n realesrnet-x4plus

# Linux/MacOS
./realesrgan-ncnn-vulkan -i input.jpg -o output.png -n realesrnet-x4plus

• Size: ~64MB
• Best for: When you want smooth results without GAN artifacts
• Speed: Medium

Usage Examples

General Images

Windows - Basic

realesrgan-ncnn-vulkan.exe -i input.jpg -o output.png -n realesrgan-x4plus

Anime Images

Anime Video Model

./realesrgan-ncnn-vulkan -i anime.jpg -o output.png -n realesr-animevideov3

Video Frames Processing

1. Extract Frames

   mkdir tmp_frames
   ffmpeg -i input.mp4 -qscale:v 1 -qmin 1 -qmax 1 -vsync 0 tmp_frames/frame%08d.png
   
2. Process Frames

   mkdir out_frames
   ./realesrgan-ncnn-vulkan -i tmp_frames -o out_frames -n realesr-animevideov3 -s 2 -f jpg
   
3. Merge Back to Video

   # Get FPS from original
   ffmpeg -i input.mp4
   
   # Merge with audio
   ffmpeg -r 23.98 -i out_frames/frame%08d.jpg -i input.mp4 \
     -map 0:v:0 -map 1:a:0 -c:a copy -c:v libx264 \
     -r 23.98 -pix_fmt yuv420p output.mp4
   

Advanced Options

With Tiling

./realesrgan-ncnn-vulkan -i large_image.jpg -o output.png -t 512

Performance Tips

Tile Size Selection

Choose tile size based on your GPU VRAM:

• 8GB+ VRAM: -t 0 (auto) or no tiling
• 4-8GB VRAM: -t 512 or -t 400
• Less than 4GB VRAM: -t 256 or -t 200

Smaller tiles use less memory but may show slight artifacts at tile boundaries.

Multi-GPU Usage

For systems with multiple GPUs:

./realesrgan-ncnn-vulkan -i input.jpg -o output.png -g 0,1,2 -t 0,0,0

This distributes processing across GPUs 0, 1, and 2.

TTA Mode

Enable TTA for potentially better quality (slower):

./realesrgan-ncnn-vulkan -i input.jpg -o output.png -x

TTA applies transformations, processes, then averages results. Best for critical images.

NCNN vs Python Implementation

Advantages

NCNN Advantages:

✓ No Python/PyTorch installation required ✓ Portable executable - works out of the box ✓ Works with Intel/AMD GPUs via Vulkan ✓ Smaller download size ✓ No CUDA requirement ✓ Easier for non-technical users

Limitations

NCNN Limitations:

✗ May produce slightly different results than PyTorch ✗ Potential block inconsistency with tiling ✗ No --outscale for arbitrary scaling ✗ No face enhancement integration ✗ No denoise strength control ✗ Fewer models available

For maximum quality and features, use the Python implementation.

Comparison

Feature	NCNN	Python
Setup	Easy	Requires Python
GPU Support	Intel/AMD/Nvidia	Nvidia (CUDA)
Face Enhancement	No	Yes
Arbitrary Scale	No	Yes
Denoise Control	No	Yes
Quality	Very Good	Excellent
Speed	Fast	Fast

Troubleshooting

Vulkan not found error

Install Vulkan drivers for your GPU:

Windows:

• Nvidia: Install latest GeForce drivers
• AMD: Install latest Radeon drivers
• Intel: Install latest graphics drivers

Linux:

# Ubuntu/Debian
sudo apt install vulkan-utils

# Check Vulkan
vulkaninfo

MacOS:

• macOS 10.15+ includes Vulkan support via MoltenVK

Out of memory error

Reduce tile size:

./realesrgan-ncnn-vulkan -i input.jpg -o output.png -t 256

Or use an even smaller tile size:

./realesrgan-ncnn-vulkan -i input.jpg -o output.png -t 128

Block artifacts in output

This is due to tiling. To minimize:

1. Use larger tile size (if memory allows):

   ./realesrgan-ncnn-vulkan -i input.jpg -o output.png -t 512
   

2. Use auto tile size:

   ./realesrgan-ncnn-vulkan -i input.jpg -o output.png -t 0
   

3. If possible, disable tiling by using the Python implementation

Model not found error

Ensure models are in the correct directory:

1. Check the models folder exists in the same directory as the executable
2. Verify model files are present
3. Specify custom model path:
   ./realesrgan-ncnn-vulkan -i input.jpg -o output.png -m /path/to/models
   

Slow processing on CPU

If using CPU instead of GPU:

1. Install proper GPU drivers
2. Verify Vulkan is working: vulkaninfo (Linux)
3. Specify GPU explicitly:
   ./realesrgan-ncnn-vulkan -i input.jpg -o output.png -g 0
   

Additional Resources

Real-ESRGAN-ncnn-vulkan

Official NCNN implementation repository

Python Inference

Full Python implementation with all features

Anime Videos

Process anime videos using NCNN

When to Use NCNN vs Python

Use NCNN When

✓ You don’t have Python installed ✓ You want a simple, portable solution ✓ You have Intel or AMD GPU (no CUDA) ✓ You need quick setup ✓ You’re processing standard images ✓ You don’t need face enhancement

Use Python When

✓ You need face enhancement ✓ You want arbitrary output scales ✓ You need denoise control ✓ You want maximum quality ✓ You have Python environment already ✓ You have Nvidia GPU with CUDA ✓ You need all available models