Install & Compatibility
Where this runs
tested against v1.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ timeout
4/12 runs
py 3.11
✕ timeout
4/12 runs
py 3.12
✕ dependency_conflict
3/12 runs
py 3.13
✕ no_wheel
✕ dependency_conflict
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RRDBNet
✓ from basicsr.archs.rrdbnet_arch import RRDBNet
✗ from basicsr.archs.rrdbnet_arch import RRDBNet
RealESRGANer
✓ from basicsr.utils.realesrgan_utils import RealESRGANer
✗ from basicsr.utils.realesrgan_utils import RealESRGANer
This quickstart demonstrates how to programmatically perform super-resolution inference using a pre-trained Real-ESRGAN model. It covers creating a dummy input image, downloading the necessary model weights, initializing the `RealESRGANer` utility, and processing the image to save the super-resolved output. The example uses a common `RealESRGAN_x4plus` model from a public URL.
import os
import cv2
import torch
import numpy as np
from basicsr.archs.rrdbnet_arch import RRDBNet
from basicsr.utils.realesrgan_utils import RealESRGANer
from basicsr.utils.download_util import load_file_from_url
# 1. Create a dummy low-resolution image (e.g., 64x64, 3 channels)
# In a real application, this would be loaded from a file (e.g., cv2.imread)
dummy_lr_img = np.random.randint(0, 256, (64, 64, 3), dtype=np.uint8)
# 2. Define model parameters and download URL for a pre-trained Real-ESRGAN model
model_scale = 4
model_path_url = "https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth"
output_filename = "dummy_sr_image.png"
# 3. Download the model weights
try:
# Model weights will be saved to a 'weights' directory by default
model_path = load_file_from_url(url=model_path_url, model_dir='weights', progress=True)
except Exception as e:
print(f"Could not download model from {model_path_url}: {e}")
model_path = None # Set to None if download fails
if model_path:
# 4. Initialize the RealESRGANer for inference
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
upsampler = RealESRGANer(
scale=model_scale,
model_path=model_path,
dni_weight=None, # Not used for standard RealESRGAN_x4plus
model_arch=RRDBNet,
tile=0, # Process image without tiling for small inputs
tile_pad=10,
pre_pad=0,
half=False, # Use float32, set to True for float16 inference if supported
device=device
)
# 5. Perform inference (enhance expects a NumPy array (HWC, BGR, uint8))
output_image, _ = upsampler.enhance(dummy_lr_img, outscale=model_scale)
# 6. Save the output image
cv2.imwrite(output_filename, output_image)
print(f"Super-resolved image saved to {output_filename}")
else:
print("Skipping quickstart inference due to model download failure or missing model path.")
# Clean up downloaded weights directory if desired (optional)
# import shutil
# if os.path.exists('weights'):
# shutil.rmtree('weights')
basicsr --version
Debug
Known issues
breakingAs of v1.4.0, BasicSR officially moved under the 'XPixelGroup' organization. While direct breaking changes for user code might be minimal, internal paths or configuration assumptions could be affected for those updating from much older versions or directly referencing internal modules.fixReview your code for any hardcoded paths or imports that might implicitly assume the old repository structure. Update to the latest version and verify functionality. Re-download any pre-trained models if paths change.
affects: <1.4.0
gotchaOlder BasicSR versions (prior to v1.4.2) could encounter `ModuleNotFoundError` for `torch` if it wasn't pre-installed. This was due to `torch` not always being in `setup_requires`, leading to a race condition or failed imports during initial setup.fixAlways ensure `torch` and `torchvision` are installed correctly for your specific CUDA version *before* installing `basicsr`. Use PyTorch's official installation instructions, e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118`.
affects: <1.4.2
gotchaBasicSR heavily relies on YAML configuration files for training and testing. Incorrect file paths, malformed YAML syntax, or missing required parameters are common sources of errors.fixCarefully review your `.yml` configuration files for correct syntax, valid paths, and all necessary parameters as outlined in the official examples. Use the `force_yml` option (available since v1.3.4.2) for command-line overrides if needed.
affects: All versions
gotchaA bug in `bgr2ycbcr` color conversion was fixed in v1.4.1. If you were using BasicSR's internal color conversion utilities in older versions for custom pipelines, your results might have been subtly incorrect.fixUpgrade to v1.4.1 or later. If using older versions and custom color conversion, consider manually implementing or verifying conversion logic with external libraries like `OpenCV` or `scikit-image`.
affects: <1.4.1
gotchaSpecific features like the official `torchvision.ops.deform_conv2d` require `torchvision>=0.9.0`. Using older `torchvision` versions might lead to compatibility issues or `AttributeError` for these advanced operators.fixEnsure your `torchvision` installation meets the minimum version requirement for the specific features you intend to use. Always follow the recommended PyTorch/Torchvision installation for your environment.
affects: <1.3.4.2 (for this specific feature)
Upgrade
Version history
1.4.2latest on PyPI · released Aug 30, 2022
Audit
Dependencies
torchrequiredCore deep learning framework. Often needs specific CUDA version installation.
torchvisionrequiredCommonly used for image transformations and datasets, sometimes required for specific features like deform_conv2d.
numpyrequiredFundamental package for numerical operations.
opencv-pythonrequiredUsed for image loading, saving, and processing.