Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RealESRGANer
✓ from realesrgan import RealESRGANer
✗ from realesrgan import RealESRGANer
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)
realesrgan --version
Debug
Known issues
gotchaFor 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.fixManually install a CUDA-enabled PyTorch version matching your system's CUDA toolkit after installing Real-ESRGAN, or ensure it's installed beforehand.
affects: All
gotchaUpscaling 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.fixWhen 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.
affects: All
breakingModel 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.fixAlways 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.
affects: v0.2.x -> v0.3.x (e.g., introduction of `realesr-general-x4v3`, updates to `AnimeVideo-v3`)
Upgrade
Version history
0.3.0latest on PyPI · released Sep 20, 2022
Audit
Dependencies
basicsrrequiredCore deep learning framework and utilities for Real-ESRGAN. Transitive dependencies include torch, torchvision, numpy, opencv-python, Pillow, etc.
torchrequiredUnderlying deep learning framework. For optimal performance, users often need to manually install a version compatible with their specific CUDA setup.