Installation

Install Real-ESRGAN and its dependencies

Prerequisites

Before installing Real-ESRGAN, ensure you have the following requirements:

Python

Python >= 3.7

PyTorch

PyTorch >= 1.7

We recommend using Anaconda or Miniconda to manage your Python environment.

Installation Steps

1. Clone the Repository

   First, clone the Real-ESRGAN repository from GitHub:

   git clone https://github.com/xinntao/Real-ESRGAN.git
   cd Real-ESRGAN
   
2. Install PyTorch

   Install PyTorch (version >= 1.7) according to your system configuration. Visit pytorch.org for installation instructions specific to your CUDA version.

   Example for CUDA 11.8:

   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
   

   Example for CPU only:

   pip install torch torchvision
   
3. Install Dependencies

   Install the required Python packages:

   # Install basicsr - https://github.com/xinntao/BasicSR
   # We use BasicSR for both training and inference
   pip install basicsr
   
   # facexlib and gfpgan are for face enhancement
   pip install facexlib
   pip install gfpgan
   
   # Install other dependencies
   pip install -r requirements.txt
   

   View requirements.txt contents

   basicsr>=1.4.2
   facexlib>=0.2.5
   gfpgan>=1.3.5
   numpy
   opencv-python
   Pillow
   torch>=1.7
   torchvision
   tqdm
   
4. Install Real-ESRGAN

   Install the Real-ESRGAN package in development mode:

   python setup.py develop
   

   Using develop mode allows you to modify the source code and have changes take effect immediately without reinstalling.

5. Verify Installation

   Verify that Real-ESRGAN is installed correctly:

   python -c "import realesrgan; print('Real-ESRGAN installed successfully!')"
   

Alternative: Install via pip

For a simpler installation without cloning the repository, you can install Real-ESRGAN directly from PyPI:

pip install realesrgan

The pip package may not include the latest features and models. For development or access to all models, we recommend installing from the source repository.

Package Dependencies

Real-ESRGAN requires the following key packages:

basicsr (>= 1.4.2)

BasicSR is an open-source image and video restoration toolbox used for both training and inference in Real-ESRGAN.

facexlib (>= 0.2.5)

A collection of face-related functions used for face detection and analysis.

gfpgan (>= 1.3.5)

GFPGAN (Generative Facial Prior GAN) is used for optional face enhancement in Real-ESRGAN.

opencv-python

OpenCV is used for image I/O operations and basic image processing.

torch (>= 1.7)

PyTorch is the deep learning framework powering Real-ESRGAN’s neural networks.

GPU Support

While Real-ESRGAN can run on CPU, using a GPU is highly recommended for practical performance. Image upscaling is significantly faster with CUDA-enabled GPUs.

To check if PyTorch can access your GPU:

python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'GPU: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else "None"}')"

Portable Executables (Alternative)

If you prefer not to set up a Python environment, portable executable files are available for Windows, Linux, and macOS:

• Windows
• Linux
• macOS

These executables use the NCNN framework and work on Intel/AMD/Nvidia GPUs without requiring Python or CUDA.

The portable executables may not support all features available in the Python implementation (such as --outscale and --face_enhance).

Troubleshooting

ImportError: No module named 'basicsr'

Make sure you’ve installed BasicSR:

pip install basicsr

CUDA out of memory

Try using the --tile option with a smaller tile size (e.g., --tile 400) to reduce memory usage during inference.

PyTorch not using GPU

Ensure you’ve installed the correct PyTorch version for your CUDA version. Visit pytorch.org to find the right installation command.

Next Steps

Quick Start Guide

Learn how to upscale your first image with Real-ESRGAN