GO — Healthy across all four use cases

• 11 active contributors
• BSD-3-Clause licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 87% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Real-ESRGAN is a practical deep learning framework for image and video super-resolution (upscaling) using generative adversarial networks. It provides pre-trained models (RealESRGAN_x4plus, x2plus, x3plus) capable of 2-4x upscaling with realistic detail restoration, plus specialized anime models (RealESRGAN_x4plus_anime_6B) and AnimeVideo-v3 for video restoration. The core contribution is real-world restoration that handles unknown degradation without paired training data. Monolithic Python project: inference_realesrgan.py and inference_realesrgan_video.py are entry points wrapping model loading; options/ directory contains YAML training configs (train_realesrgan_x4plus.yml, finetune_realesrgan_x4plus.yml); docs/ organizes guides (Training.md, model_zoo.md, CONTRIBUTING.md); inputs/ provides test images; experiments/pretrained_models/ references downloadable weights. Core logic likely in imported basicsr package (not shown in file list).

Computer vision engineers, image restoration researchers, and end-users who need to upscale photos, historical images, or anime content. Contributors include deep learning practitioners implementing training pipelines in options/*.yml and researchers integrating restoration into larger applications (see inference_realesrgan.py and cog_predict.py for deployment patterns).

Production-ready. The project has accumulated 25k+ GitHub stars, is actively maintained with CI/CD via GitHub Actions (.github/workflows/ with pylint and PyPI publishing), publishes to pip as 'realesrgan' package, and maintains comprehensive model zoo (docs/model_zoo.md). However, the last visible commit date is not provided in the data, so assume active if recent GH activity exists.

Low-to-moderate risk. Dependencies are well-scoped (basicsr>=1.4.2, facexlib>=0.2.5, gfpgan>=1.3.5, torch>=1.7) and maintained by the same team. Single maintainer risk exists (xinntao). Main concern: model files are hosted externally in experiments/pretrained_models/ (not in repo), so download failures could break inference. No visible breaking-change history in provided data.

Active feature development: anime-specialized models (RealESRGAN_x4plus_anime_6B, AnimeVideo-v3) released recently per README; video inference path actively maintained (inference_realesrgan_video.py). CI/CD automated via GitHub Actions. Replicate demo integration live. Training documentation updated (Training_CN.md added). No specific PR data visible, but release workflow (.github/workflows/release.yml) and pip publishing suggest regular version bumps.

git clone https://github.com/xinntao/Real-ESRGAN.git && cd Real-ESRGAN && pip install -e . (editable install of the package, inferred from MANIFEST.in and setup patterns). To test immediately: python inference_realesrgan.py -n RealESRGAN_x4plus -i inputs/0030.jpg -o results -s 4

Daily commands: For inference: python inference_realesrgan.py -n RealESRGAN_x4plus -i <input_image> -o <output_dir> -s 4. For video: python inference_realesrgan_video.py -i <input_video> -o <output_dir> -n RealESRGAN_x4plus. For training: edit options/train_realesrgan_x4plus.yml and invoke via basicsr's training script (documented in docs/Training.md). Docker/Cog entrypoint via cog_predict.py.

• realesrgan/models/realesrgan_model.py — Core training and inference model implementing the Real-ESRGAN algorithm; essential for understanding the main ML pipeline.
• realesrgan/archs/srvgg_arch.py — Generator architecture definition; foundational to model construction and must be understood before modifying model behavior.
• inference_realesrgan.py — Primary entry point for image upscaling; demonstrates the end-to-end inference workflow contributors need to know.
• realesrgan/data/realesrgan_dataset.py — Dataset loading and preprocessing logic; critical for training and understanding data flow through the model.
• realesrgan/train.py — Training script orchestrator; required reading for anyone extending training functionality or modifying loss functions.
• requirements.txt — Declares dependency on basicsr, facexlib, and gfpgan; essential for environment setup and understanding external model integration.
• docs/model_zoo.md — Reference for all available pretrained models and their intended use cases; guides model selection for different tasks.

Add a new generator architecture variant

1. Create new architecture class in realesrgan/archs/ inheriting from nn.Module (realesrgan/archs/srvgg_arch.py)
2. Register architecture in realesrgan/archs/init.py (realesrgan/archs/__init__.py)
3. Update model config to instantiate new architecture via 'network_g_type' parameter (options/train_realesrgan_x4plus.yml)
4. Add unit test in tests/ to validate forward pass (tests/test_discriminator_arch.py)

Add support for a new dataset format

1. Create new dataset class inheriting from torch.utils.data.Dataset in realesrgan/data/ (realesrgan/data/realesrgan_dataset.py)
2. Register dataset in realesrgan/data/init.py and update import statements (realesrgan/data/__init__.py)
3. Add dataset type selector in training config under 'train_dataset'/'val_dataset' section (options/train_realesrgan_x4plus.yml)
4. Create test case with sample data in tests/data/ (tests/test_dataset.py)

Add a new loss function to training

1. Define loss computation in realesrgan/models/realesrgan_model.py's optimize_parameters() method (realesrgan/models/realesrgan_model.py)
2. Add loss weight parameter to training config under 'l_*_weight' (options/train_realesrgan_x4plus.yml)
3. Update log_dict to track new loss in model.py (realesrgan/models/realesrgan_model.py)
4. Test convergence with minimal dataset using test config (tests/data/test_realesrgan_model.yml)

Create a custom inference wrapper for production

1. Reference inference_realesrgan.py for model loading and preprocessing patterns (inference_realesrgan.py)
2. Use RealESRGANer class from realesrgan module for batch inference (realesrgan/__init__.py)
3. Implement caching/batching logic similar to cog_predict.py (cog_predict.py)
4. Document setup in docs/Training.md or create new docs file (docs/Training.md)

• PyTorch + basicsr — PyTorch enables flexible GAN training with dynamic computation graphs; basicsr provides pre-built training loops, metrics, and distributed training utilities to reduce boilerplate.
• LMDB datasets (tests/data/) — LMDB provides fast random access to large training datasets while minimizing I/O overhead during multi-epoch training on commodity hardware.
• YAML config files (options/) — YAML enables non-programmers to modify hyperparameters, model architectures, and data paths without touching Python code; integrates with basicsr's config system.
• Cog wrapper (cog_predict.py, cog.yaml) — Cog containerizes the inference service for Replicate.com deployment, enabling zero-install cloud inference while maintaining local development simplicity.

• Unpaired degradation synthesis (realesrgan_dataset.py) vs. paired supervised data

  • Why: Generating degradations on-the-fly increases training time but avoids need for aligned GT/LQ pairs, enabling use of any high-quality image dataset.
  • Consequence: Training slower (~2–3 weeks on 8 V100s) but applicable to real-world degradations; paired fine-tuning available in options/finetune_realesrgan_x4plus_pairdata.yml.

• Tile-based inference (inference_realesrgan.py) instead of single-pass

  • Why: Reduces peak GPU memory from ~24GB (full 4K image) to ~2–6GB (tile), enabling inference on consumer GPUs.
  • Consequence: Minor edge artifacts at tile boundaries (mitigated with overlap); ~5–10% inference slowdown vs. single-pass on high-end GPUs.

• Dependency on facexlib and gfpgan (optional)

  • Why: Real-ESRGAN handles general upscaling; facexlib/gfpgan add specialized face restoration as post-processing without requiring retraining.
  • Consequence: Larger wheel size (~200MB) but modular design; users can omit if not needed.

• SRVGG lightweight architecture vs. ResNet/DenseNet

  • Why: SRVGG is 10–50× smaller than standard GANs (~4M params) for faster deployment and lower memory; still achieves competitive visual quality.
  • Consequence: Slightly reduced detail recovery on extreme degradations; better trade-off for mobile/edge deployment.

• Real-time video restoration (inference_realesrgan_video.py is not optimized for live streams; designed for offline frame-by-frame processing)
• Video compression or codec support (only reads MP4; no encoding

1. Model weights are not in the repo; they download on first inference from external URLs specified in basicsr registry (slow on first run, requires internet). 2. YAML configs in options/ reference dataset paths like 'datasets/DIV2K' that must exist locally for training; no validation script provided. 3. Tile inference (tiling.py in realesrgan package) is critical for large images but details hidden; if you OOM, adjust tile_size in inference_realesrgan.py. 4. Anime models use different training data; mixing them with general models may produce artifacts. 5. Video inference requires consistent frame dimensions; video codec errors are not always caught early.

• Generative Adversarial Networks (GANs) — Real-ESRGAN uses an adversarial loss (generator vs discriminator) to produce perceptually realistic details in upscaled images rather than just minimizing MSE.
• Residual Dense Blocks (RRDBNet) — The core architecture of Real-ESRGAN models; skip connections and dense blocks enable training very deep networks without gradient vanishing.
• Tile-based inference — Real-ESRGAN processes large images by dividing them into overlapping tiles, reconstructing, and blending; critical for GPU memory constraints and handled transparently in inference_realesrgan.py.
• Blind image restoration / Unsupervised degradation — Real-ESRGAN doesn't require paired low-res/high-res training data; it learns to restore unknown degradations using a degradation model—why it works on real-world photos without retraining.
• YAML-driven configuration (MLOps pattern) — All training hyperparameters (network depth, learning rate, batch size, loss weights) live in options/*.yml, not hardcoded; enables reproducibility and grid search without code changes.
• Perceptual loss / Feature-matching loss — Real-ESRGAN uses pre-trained VGG features (via basicsr) as loss, not just pixel-level L1; produces sharper, more realistic upscales than naive MSE minimization.
• Model quantization and NCNN deployment — Portable Windows/Linux/macOS executables (mentioned in README) use NCNN quantization; docs/ncnn_conversion.md explains converting PyTorch → NCNN for CPU/GPU inference without Python.

• xinntao/GFPGAN — Sibling project by same author for face restoration; often used together with Real-ESRGAN in pipelines (required by gfpgan>=0.2.5 dependency).
• xinntao/BasicSR — Core training and model infrastructure library that Real-ESRGAN depends on; contains RRDBNet, losses, and training loops imported throughout this repo.
• upscayl/upscayl — Desktop GUI wrapper around Real-ESRGAN models using NCNN (see ncnn_conversion.md); alternative distribution method for end-users.
• nagadomi/waifu2x — Predecessor anime upscaling project; Real-ESRGAN anime models (RealESRGAN_x4plus_anime_6B) directly inspired by and improve upon this approach.
• openmmlab/mmediting — Broader computer vision editing framework that includes super-resolution; BasicSR is spun out from this, useful for understanding architecture evolution.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for realesrgan/utils.py and realesrgan/archs modules

The repo lacks dedicated unit tests. Currently there are CI workflows for pylint and release, but no testing workflow. The utils.py module and architecture files (srvgg_arch.py, discriminator_arch.py) are critical utilities that would benefit from test coverage. This ensures model loading, inference utilities, and architecture initialization work correctly across different input scenarios and edge cases.

• [ ] Create tests/ directory with init.py
• [ ] Add tests/test_utils.py covering functions in realesrgan/utils.py
• [ ] Add tests/test_archs.py testing model instantiation and forward passes for srvgg_arch.py and discriminator_arch.py
• [ ] Add GitHub Action workflow .github/workflows/tests.yml to run pytest on PR/push
• [ ] Add pytest to requirements.txt

Add integration tests for inference pipelines (inference_realesrgan.py and inference_realesrgan_video.py)

The repo provides two main inference scripts but has no automated testing to verify they work end-to-end with sample inputs. This is critical for ensuring the primary user-facing functionality doesn't break. Integration tests would validate model loading, image/video processing, output generation, and CLI argument handling.

• [ ] Create tests/test_inference.py with test functions for image inference
• [ ] Create tests/test_inference_video.py with test functions for video inference
• [ ] Add test fixtures in tests/conftest.py to download or cache small pretrained models
• [ ] Update .github/workflows/tests.yml to include integration test steps
• [ ] Add test_inputs/ directory with small sample images and videos for CI runs

Document training pipeline and add validation tests for realesrgan/train.py and model files

While docs/Training.md and docs/Training_CN.md exist, there are no automated tests verifying that training configurations in options/*.yml can be parsed and initialized correctly. The realesrgan/models/realesrgan_model.py and realesrnet_model.py are complex, and configuration errors aren't caught until training starts. Adding schema validation and model initialization tests would catch config issues early.

• [ ] Create tests/test_train_config.py to validate all YAML configs in options/ directory parse and load
• [ ] Add tests/test_model_initialization.py to verify realesrgan_model.py and realesrnet_model.py can be instantiated with valid configs
• [ ] Create a validation script scripts/validate_configs.py to check YAML structure against expected schema
• [ ] Add a note in docs/CONTRIBUTING.md requiring config validation before submitting training-related PRs
• [ ] Update .github/workflows/pylint.yml or create .github/workflows/validate.yml to run config validation

• Add pytest-based test suite for inference_realesrgan.py and inference_realesrgan_video.py with synthetic test images in tests/; currently no tests/ directory exists, blocking regression detection.
• Enhance docs/FAQ.md with troubleshooting for common failures: CUDA out-of-memory, model download timeouts, corrupted PNG alpha channels (tree_alpha_16bit.png in inputs/ suggests alpha handling edge cases).
• Create a setup.py or pyproject.toml explicit dependency lock (currently relies on implicit basicsr version; pin all versions in requirements-dev.txt for reproducibility across Python 3.8-3.11).

• Medium · Outdated and Vulnerable Dependencies — requirements.txt. The requirements.txt specifies 'torch>=1.7' which is significantly outdated (released in 2020). PyTorch 1.7 and early versions have known security vulnerabilities and lack security patches. Similarly, 'basicsr>=1.4.2', 'facexlib>=0.2.5', and 'gfpgan>=1.3.5' are loose version constraints that may install vulnerable versions. Dependencies like 'opencv-python' and 'Pillow' without upper bounds could introduce breaking changes or security issues. Fix: Update all dependencies to recent stable versions with known security patches. Use pinned versions or tight version ranges (e.g., 'torch>=2.0,<3.0'). Conduct a security audit using tools like 'safety' or 'pip-audit' to identify CVEs in current versions.
• Medium · Unvalidated External Model Downloads — inference_realesrgan.py, inference_realesrgan_video.py, realesrgan/models/. The codebase appears to download pretrained models (referenced in 'docs/model_zoo.md' and 'experiments/pretrained_models/README.md'). If model downloads are not validated via checksums or signatures, attackers could perform man-in-the-middle attacks to inject malicious models that execute arbitrary code during inference. Fix: Implement cryptographic verification (SHA256 checksums or GPG signatures) for all downloaded models. Store checksums in a signed manifest file. Validate downloads before loading. Document the verification process for users.
• Medium · Unsafe YAML Processing in Training Configuration — options/ directory, realesrgan/train.py (likely uses YAML loading). Training configuration files (in 'options/*.yml') are YAML format. If these files are loaded using 'yaml.load()' without a safe loader, YAML deserialization attacks could allow arbitrary code execution. This is particularly risky if users accept YAML configs from untrusted sources. Fix: Use 'yaml.safe_load()' instead of 'yaml.load()' for parsing configuration files. If code execution is needed, use an alternative configuration format or strictly validate YAML content.
• Low · Potential Path Traversal in File Operations — scripts/extract_subimages.py, scripts/generate_meta_info.py, inference_realesrgan.py, inference_realesrgan_video.py. The codebase processes input images and videos from 'inputs/' directory and generates outputs. If file paths are constructed from user input without proper validation in scripts like 'scripts/extract_subimages.py' or 'scripts/generate_meta_info.py', path traversal attacks could read/write files outside intended directories. Fix: Validate and sanitize all file paths using 'os.path.abspath()' and verify they remain within expected directories. Use 'pathlib.Path' for safer path handling. Implement input validation to reject paths containing '..' or absolute paths.
• Low · Missing Input Validation for Image/Video Files — inference_realesrgan.py, inference_realesrgan_video.py. The inference scripts process image and video files. If file type validation is insufficient, users could supply malicious files (e.g., crafted PNG/MP4 files) that trigger vulnerabilities in OpenCV or PIL/Pillow libraries. Fix: Validate file types by checking magic bytes/headers, not just file extensions. Use strict size limits on inputs. Handle exceptions from image/video libraries gracefully to prevent information disclosure.
• Low · Lack of Security Headers in Web Interface (cog_predict.py) — cog_predict.py. The 'cog_predict.py' file suggests a Cog-based API interface. If this exposes a web service, missing security headers (CORS, CSP, X-Frame-Options) could enable cross-site attacks. Fix: If exposing via HTTP/REST API, add security headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security, and configure CORS appropriately.
• Low · Potential Information Disclosure via Error Messages — undefined. Training and inference scripts may expose sensitive information (file paths, system details, stack traces) in error messages Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/xinntao/Real-ESRGAN shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live xinntao/Real-ESRGAN repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/xinntao/Real-ESRGAN.

What it runs against: a local clone of xinntao/Real-ESRGAN — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in xinntao/Real-ESRGAN | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 671 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of xinntao/Real-ESRGAN. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/xinntao/Real-ESRGAN.git
#   cd Real-ESRGAN
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of xinntao/Real-ESRGAN and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "xinntao/Real-ESRGAN(\\.git)?\\b" \\
  && ok "origin remote is xinntao/Real-ESRGAN" \\
  || miss "origin remote is not xinntao/Real-ESRGAN (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "realesrgan/models/realesrgan_model.py" \\
  && ok "realesrgan/models/realesrgan_model.py" \\
  || miss "missing critical file: realesrgan/models/realesrgan_model.py"
test -f "realesrgan/archs/srvgg_arch.py" \\
  && ok "realesrgan/archs/srvgg_arch.py" \\
  || miss "missing critical file: realesrgan/archs/srvgg_arch.py"
test -f "inference_realesrgan.py" \\
  && ok "inference_realesrgan.py" \\
  || miss "missing critical file: inference_realesrgan.py"
test -f "realesrgan/data/realesrgan_dataset.py" \\
  && ok "realesrgan/data/realesrgan_dataset.py" \\
  || miss "missing critical file: realesrgan/data/realesrgan_dataset.py"
test -f "realesrgan/train.py" \\
  && ok "realesrgan/train.py" \\
  || miss "missing critical file: realesrgan/train.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 671 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~641d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/xinntao/Real-ESRGAN"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.