Real-ESRGAN

Common errors

• ModuleNotFoundError: No module named 'realesrgan'

  cause The `realesrgan` package is not installed in your current Python environment.
  fix Run `pip install realesrgan`.

• RuntimeError: CUDA out of memory. Tried to allocate X GiB (GPU X; X GiB total capacity; X GiB already allocated; X GiB free; X GiB reserved in total by PyTorch)

  cause The GPU does not have enough VRAM to process the image at the specified resolution or tile size.
  fix Reduce the `tile` parameter in `RealESRGANer` (e.g., `tile=600`). For extremely large images or limited VRAM, process the image in even smaller custom chunks outside the library's tiling mechanism, or use the CLI with `--tile` option.

• FileNotFoundError: [Errno 2] No such file or directory: '/path/to/your/model.pth'

  cause The `model_path` provided to `RealESRGANer` does not point to an existing model file, or the auto-download feature failed due to network issues or an invalid `model_name`.
  fix Verify the `model_path` is correct. If relying on auto-download, ensure you have an active internet connection and that the `model_name` is valid and spelled correctly (e.g., `RealESRGAN_x4plus`). Check `~/.cache/realesrgan/` for downloaded models.

• AttributeError: 'NoneType' object has no attribute 'cpu'

  cause This error often occurs if the deep learning model (`netG`) failed to load or initialize properly, leaving `self.netG` as `None` before an operation like `.cpu()` is called.
  fix Check for preceding errors related to model loading (e.g., `FileNotFoundError` for the model, or issues with `basicsr` dependencies). Ensure the `model_path` or `model_name` is valid and accessible, and that all core dependencies like `basicsr` and `torch` are correctly installed.

Warnings

• gotcha For GPU acceleration, ensure you have PyTorch installed with CUDA support. `pip install realesrgan` only installs the CPU-compatible PyTorch if not already present. For optimal performance, `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` (or your CUDA version) might be needed.
  Fix: Manually install a CUDA-enabled PyTorch version matching your system's CUDA toolkit after installing Real-ESRGAN, or ensure it's installed beforehand.
• gotcha Upscaling large images can quickly lead to 'CUDA out of memory' errors, even on GPUs with substantial VRAM. Real-ESRGAN processes images in 'tiles' to mitigate this, but default settings might be too aggressive.
  Fix: When initializing `RealESRGANer`, set the `tile` parameter to a smaller value (e.g., 600 or 1000) to process the image in smaller chunks. Experiment with values to find what fits your VRAM.
• breaking Model names and availability can change between versions. Older models might be deprecated or new, more robust models introduced, potentially requiring updates to `model_name` or `model_path` in your code.
  Fix: Always check the latest Real-ESRGAN GitHub README or release notes for updated model names. Ensure `model_name` parameter matches an officially supported model for auto-download, or provide a verified `model_path` to a local file.

Install

• pip install realesrgan Standard installation

Imports

• RealESRGANer
  wrong:

  from realesrgan.utils import RealESRGANer

  correct:

  from realesrgan import RealESRGANer

  While RealESRGANer is in `realesrgan.utils`, it is exposed directly under the top-level `realesrgan` package for easier access since v0.2.1.

Quickstart

This quickstart demonstrates how to use `RealESRGANer` to upscale a dummy image programmatically. It uses the `RealESRGAN_x4plus` model, which will be automatically downloaded on first use. By default, it runs on CPU, but can be switched to 'cuda' for GPU acceleration if PyTorch with CUDA is installed.

import os
from PIL import Image
import numpy as np

# Assuming realesrgan is installed via pip
try:
    from realesrgan import RealESRGANer
except ImportError:
    print("RealESRGAN is not installed. Please run 'pip install realesrgan'")
    exit(1)

# Create a dummy image for demonstration
input_image_path = "temp_input_64x64.png"
output_image_path = "temp_output_upscaled.png"
dummy_image = Image.new('RGB', (64, 64), color = 'red')
dummy_image.save(input_image_path)

try:
    # Initialize RealESRGANer with a common model (auto-downloads if not present)
    # Using 'cpu' for device ensures it runs without a CUDA setup.
    # For GPU, change 'cpu' to 'cuda' and ensure PyTorch with CUDA is installed.
    upscaler = RealESRGANer(
        model_name='RealESRGAN_x4plus', # A widely used general-purpose model
        netscale=4, # The upsampling factor the model was trained for
        outscale=4, # Desired output upsampling factor (should match netscale for best results)
        tile=0, # Set to 0 to process the entire image at once. For large images/limited VRAM, use e.g. 600.
        tile_pad=10,
        pre_pad=0,
        device='cpu' # Use 'cuda' if a compatible GPU and PyTorch+CUDA are available
    )

    # Load and convert image
    img = Image.open(input_image_path).convert('RGB')
    img_np = np.array(img) # Convert PIL Image to NumPy array for processing

    # Perform enhancement
    upscaled_image_np, _ = upscaler.enhance(img_np, outscale=4)

    # Convert back to PIL Image and save
    upscaled_image_pil = Image.fromarray(upscaled_image_np)
    upscaled_image_pil.save(output_image_path)

    print(f"Image upscaled successfully and saved to {output_image_path}")

except Exception as e:
    print(f"An error occurred during upscaling: {e}")
    print("Common issues: missing models (check network), CUDA not available/misconfigured, out of memory.")
    if "cuda" in str(e).lower() and "memory" in str(e).lower():
        print("Consider reducing `tile` size in RealESRGANer or processing smaller images.")
    if "model_name" in str(e) or "model_path" in str(e):
        print("Ensure the specified `model_name` is valid or `model_path` points to an existing model file.")
finally:
    # Clean up dummy files
    if os.path.exists(input_image_path):
        os.remove(input_image_path)
    if os.path.exists(output_image_path):
        os.remove(output_image_path)