Skip to main content

​
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 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

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
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

By default, Real-ESRGAN uses FP16 for faster inference. Only use --fp32 if you experience quality issues.
For large images, experiment with different tile sizes to find the best balance between speed and memory usage.
Place multiple images in the input folder to process them in a single run.
Always use a CUDA-enabled GPU for practical performance. CPU inference is extremely slow.

​
Troubleshooting

Solution: Use the --tile option with a smaller tile size:
python inference_realesrgan.py -n RealESRGAN_x4plus -i inputs --tile 200
Solution: Check that your input image is valid and not corrupted. Also ensure you have enough disk space for the output.
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

Build docs developers (and LLMs) love

Get started for freeTalk to us