Quick Start

Get started with Real-ESRGAN image upscaling

Basic Usage

Real-ESRGAN provides a simple command-line interface for upscaling images. This guide will walk you through your first image enhancement.

Download a Pre-trained Model

Before running inference, you need to download a pre-trained model. Let’s start with the general-purpose RealESRGAN_x4plus model:

wget

wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P weights

The model will be automatically downloaded to the weights directory if it’s not found when running inference.

Upscale Your First Image

1. Prepare Your Input

   Place your input image(s) in a folder. The default input folder is inputs:

   mkdir -p inputs
   cp /path/to/your/image.jpg inputs/
   
2. Run Inference

   Use the inference_realesrgan.py script to upscale your image:

   python inference_realesrgan.py -n RealESRGAN_x4plus -i inputs
   

   This command will:

   • Use the RealESRGAN_x4plus model
   • Process all images in the inputs folder
   • Save results to the results folder (default output directory)
3. Check Results

   Your upscaled images will be in the results folder:

   ls results/
   

Command-Line Options

The inference script provides many options for customization:

python inference_realesrgan.py -n RealESRGAN_x4plus -i infile --outscale 3.5 --face_enhance

Available Arguments

-i, --input · string · default: "inputs"

Input image or folder path

-o, --output · string · default: "results"

Output folder path

-n, --model_name · string · default: "RealESRGAN_x4plus"

Model name. Options:

• RealESRGAN_x4plus - General images (default)
• RealESRGAN_x4plus_anime_6B - Anime images
• RealESRNet_x4plus - Alternative general model
• RealESRGAN_x2plus - 2x upscaling
• realesr-animevideov3 - Anime videos
• realesr-general-x4v3 - General scenes (small model)

-s, --outscale · float · default: "4"

The final upsampling scale. Allows arbitrary output sizes (e.g., 3.5x)

--suffix · string · default: "out"

Suffix for the restored image filename

-t, --tile · int · default: "0"

Tile size for processing large images. Use this to reduce GPU memory usage. Set to 0 for no tiling. Recommended values: 200-400 for limited VRAM

--face_enhance · boolean

Enable GFPGAN face enhancement

--fp32 · boolean

Use FP32 precision instead of FP16. Slower but may improve quality on some images

--ext · string · default: "auto"

Output image extension. Options: auto, jpg, png

-g, --gpu-id · int

GPU device ID to use (e.g., 0, 1, 2 for multi-GPU systems)

Common Examples

Upscale General Images

Basic 4x upscaling

python inference_realesrgan.py -n RealESRGAN_x4plus -i inputs

Upscale Anime Images

For anime illustrations, use the specialized anime model:

# Download the anime model
wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.2.4/RealESRGAN_x4plus_anime_6B.pth -P weights

# Run inference
python inference_realesrgan.py -n RealESRGAN_x4plus_anime_6B -i inputs

The anime model (RealESRGAN_x4plus_anime_6B) is optimized specifically for anime-style artwork and has a smaller model size compared to the general model.

Face Enhancement

Enhance faces in your images using integrated GFPGAN:

python inference_realesrgan.py -n RealESRGAN_x4plus -i inputs --face_enhance

Face enhancement requires the gfpgan package to be installed. See the installation guide for details.

Handle Large Images

If you encounter CUDA out of memory errors, use the tile option:

python inference_realesrgan.py -n RealESRGAN_x4plus -i inputs --tile 400

Understanding Tiling

The --tile option splits large images into smaller tiles for processing, then stitches them back together. This reduces GPU memory usage but may introduce slight inconsistencies at tile boundaries.

Recommended tile sizes:

• 4GB VRAM: --tile 200
• 6GB VRAM: --tile 300
• 8GB+ VRAM: --tile 400 or no tiling

Python API Usage

You can also use Real-ESRGAN programmatically in your Python scripts:

import cv2
from basicsr.archs.rrdbnet_arch import RRDBNet
from realesrgan import RealESRGANer

# Define the model
model = RRDBNet(
    num_in_ch=3,
    num_out_ch=3,
    num_feat=64,
    num_block=23,
    num_grow_ch=32,
    scale=4
)

# Create upsampler
upsampler = RealESRGANer(
    scale=4,
    model_path='weights/RealESRGAN_x4plus.pth',
    model=model,
    tile=0,
    tile_pad=10,
    pre_pad=0,
    half=True,  # Use FP16 for faster inference
    gpu_id=0
)

# Read image
img = cv2.imread('inputs/image.jpg', cv2.IMREAD_UNCHANGED)

# Upscale
output, _ = upsampler.enhance(img, outscale=4)

# Save result
cv2.imwrite('outputs/image_upscaled.jpg', output)

API with Face Enhancement

import cv2
from basicsr.archs.rrdbnet_arch import RRDBNet
from realesrgan import RealESRGANer
from gfpgan import GFPGANer

# Define the model
model = RRDBNet(
    num_in_ch=3,
    num_out_ch=3,
    num_feat=64,
    num_block=23,
    num_grow_ch=32,
    scale=4
)

# Create upsampler
upsampler = RealESRGANer(
    scale=4,
    model_path='weights/RealESRGAN_x4plus.pth',
    model=model,
    tile=0,
    tile_pad=10,
    pre_pad=0,
    half=True,
    gpu_id=0
)

# Create face enhancer
face_enhancer = GFPGANer(
    model_path='https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.3.pth',
    upscale=4,
    arch='clean',
    channel_multiplier=2,
    bg_upsampler=upsampler
)

# Read image
img = cv2.imread('inputs/portrait.jpg', cv2.IMREAD_UNCHANGED)

# Enhance with face enhancement
_, _, output = face_enhancer.enhance(
    img,
    has_aligned=False,
    only_center_face=False,
    paste_back=True
)

# Save result
cv2.imwrite('outputs/portrait_enhanced.jpg', output)

Supported Image Formats

Real-ESRGAN supports various image formats and types:

RGB Images

Standard color images (JPG, PNG, WebP)

RGBA Images

Images with alpha channel transparency

Grayscale

Single-channel grayscale images

16-bit Images

High bit-depth images for professional workflows

Performance Tips

Use FP16 (Half Precision)

By default, Real-ESRGAN uses FP16 for faster inference. Only use --fp32 if you experience quality issues.

Optimize Tile Size

For large images, experiment with different tile sizes to find the best balance between speed and memory usage.

Batch Processing

Place multiple images in the input folder to process them in a single run.

Use GPU

Always use a CUDA-enabled GPU for practical performance. CPU inference is extremely slow.

Troubleshooting

CUDA out of memory

Solution: Use the --tile option with a smaller tile size:

python inference_realesrgan.py -n RealESRGAN_x4plus -i inputs --tile 200

RuntimeError during inference

Solution: Check that your input image is valid and not corrupted. Also ensure you have enough disk space for the output.

Model not found

Solution: The model will be automatically downloaded. Ensure you have internet connectivity and write permissions in the weights folder.

Next Steps

Model Zoo

Explore all available models and their use cases

Training Guide

Learn how to train Real-ESRGAN on your own dataset