{"id":10191,"library":"realesrgan","title":"Real-ESRGAN","description":"Real-ESRGAN provides state-of-the-art practical algorithms for general image restoration, particularly focusing on super-resolution. It is currently at version 0.3.0 and sees active development with several minor and major releases annually, bringing new models and features.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/xinntao/Real-ESRGAN","tags":["image processing","super resolution","deep learning","computer vision","image restoration","upscaling"],"install":[{"cmd":"pip install realesrgan","lang":"bash","label":"Standard installation"}],"dependencies":[{"reason":"Core deep learning framework and utilities for Real-ESRGAN. Transitive dependencies include torch, torchvision, numpy, opencv-python, Pillow, etc.","package":"basicsr","optional":false},{"reason":"Underlying deep learning framework. For optimal performance, users often need to manually install a version compatible with their specific CUDA setup.","package":"torch","optional":false}],"imports":[{"note":"While RealESRGANer is in `realesrgan.utils`, it is exposed directly under the top-level `realesrgan` package for easier access since v0.2.1.","wrong":"from realesrgan.utils import RealESRGANer","symbol":"RealESRGANer","correct":"from realesrgan import RealESRGANer"}],"quickstart":{"code":"import os\nfrom PIL import Image\nimport numpy as np\n\n# Assuming realesrgan is installed via pip\ntry:\n    from realesrgan import RealESRGANer\nexcept ImportError:\n    print(\"RealESRGAN is not installed. Please run 'pip install realesrgan'\")\n    exit(1)\n\n# Create a dummy image for demonstration\ninput_image_path = \"temp_input_64x64.png\"\noutput_image_path = \"temp_output_upscaled.png\"\ndummy_image = Image.new('RGB', (64, 64), color = 'red')\ndummy_image.save(input_image_path)\n\ntry:\n    # Initialize RealESRGANer with a common model (auto-downloads if not present)\n    # Using 'cpu' for device ensures it runs without a CUDA setup.\n    # For GPU, change 'cpu' to 'cuda' and ensure PyTorch with CUDA is installed.\n    upscaler = RealESRGANer(\n        model_name='RealESRGAN_x4plus', # A widely used general-purpose model\n        netscale=4, # The upsampling factor the model was trained for\n        outscale=4, # Desired output upsampling factor (should match netscale for best results)\n        tile=0, # Set to 0 to process the entire image at once. For large images/limited VRAM, use e.g. 600.\n        tile_pad=10,\n        pre_pad=0,\n        device='cpu' # Use 'cuda' if a compatible GPU and PyTorch+CUDA are available\n    )\n\n    # Load and convert image\n    img = Image.open(input_image_path).convert('RGB')\n    img_np = np.array(img) # Convert PIL Image to NumPy array for processing\n\n    # Perform enhancement\n    upscaled_image_np, _ = upscaler.enhance(img_np, outscale=4)\n\n    # Convert back to PIL Image and save\n    upscaled_image_pil = Image.fromarray(upscaled_image_np)\n    upscaled_image_pil.save(output_image_path)\n\n    print(f\"Image upscaled successfully and saved to {output_image_path}\")\n\nexcept Exception as e:\n    print(f\"An error occurred during upscaling: {e}\")\n    print(\"Common issues: missing models (check network), CUDA not available/misconfigured, out of memory.\")\n    if \"cuda\" in str(e).lower() and \"memory\" in str(e).lower():\n        print(\"Consider reducing `tile` size in RealESRGANer or processing smaller images.\")\n    if \"model_name\" in str(e) or \"model_path\" in str(e):\n        print(\"Ensure the specified `model_name` is valid or `model_path` points to an existing model file.\")\nfinally:\n    # Clean up dummy files\n    if os.path.exists(input_image_path):\n        os.remove(input_image_path)\n    if os.path.exists(output_image_path):\n        os.remove(output_image_path)","lang":"python","description":"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."},"warnings":[{"fix":"Manually install a CUDA-enabled PyTorch version matching your system's CUDA toolkit after installing Real-ESRGAN, or ensure it's installed beforehand.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":"v0.2.x -> v0.3.x (e.g., introduction of `realesr-general-x4v3`, updates to `AnimeVideo-v3`)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install realesrgan`.","cause":"The `realesrgan` package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'realesrgan'"},{"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.","cause":"The GPU does not have enough VRAM to process the image at the specified resolution or tile size.","error":"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)"},{"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.","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`.","error":"FileNotFoundError: [Errno 2] No such file or directory: '/path/to/your/model.pth'"},{"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.","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.","error":"AttributeError: 'NoneType' object has no attribute 'cpu'"}]}