Restoria

Note: We are rebranding and rebooting this project as Restoria — intelligent image revival. The new primary CLI is restoria; existing commands remain available during the transition. See docs/guides/migration.md.

Restoria Logo

Why Restoria?

Quick start

Try a single image restoration in 30 seconds:

# Install
pip install gfpgan

# Restore a photo
gfpgan-infer --input path/to/photo.jpg --version 1.3 --upscale 2

# Results saved to results/ with before/after comparison

Open in Colab

Quick CLI Usage

Note: on CPU, Real-ESRGAN background upsampling is disabled for speed.

Restoria quick examples

Try the new modular CLI (Restoria) side-by-side with legacy commands:

# Single image (plan-only, no execution; writes plan + manifest)
restoria run --input assets/gfpgan_logo.png --output out/ --plan-only

# Single image (run through default backend)
restoria run --input assets/gfpgan_logo.png --output out/

# Folder
restoria run --input inputs/whole_imgs --output out_folder/

# Discover backends and check environment
restoria list-backends
restoria doctor

Colab Features

Compatibility notes (Torch/Torchvision/Basicsr)

See docs/COMPATIBILITY.md for a quick matrix and notes.

:question: Frequently Asked Questions can be found in FAQ.md.

Core capabilities

Single image restoration

Restore individual photos with simple CLI or drag-and-drop web interface:

gfpgan-infer --input damaged_photo.jpg --version 1.3

Batch processing

Process entire folders with consistent settings and quality metrics:

gfpgan-infer --input photos/ --backend gfpgan --metrics fast --output restored/

Background enhancement

Combine face restoration with background upscaling using Real-ESRGAN:

gfpgan-infer --input photo.jpg --upscale 2 --bg_upsampler realesrgan

Supported platforms

Platform GPU Acceleration Status
Linux CUDA 11.8+ / ROCm ✅ Full support
Windows CUDA / DirectML ✅ Full support
macOS Metal Performance Shaders ✅ Full support
CPU-only All platforms ✅ Slower, but works

Documentation

Key guides

:question: Questions? Check our FAQ or troubleshooting guide.

Installation

Quick install

pip install gfpgan

Development install

git clone https://github.com/IAmJonoBo/Restoria.git
cd Restoria
pip install -e ".[dev,metrics,web]"

GPU acceleration

NVIDIA (CUDA): Install PyTorch with CUDA support first:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

Apple Silicon (MPS): Works out of the box with recent PyTorch versions.

AMD (ROCm): Install ROCm-compatible PyTorch:

pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm5.6

For detailed platform-specific instructions, see our hardware guide.

CLI usage

Basic restoration

# Restore a single image
gfpgan-infer --input photo.jpg --version 1.3

# Process a folder
gfpgan-infer --input photos/ --output results/ --version 1.3

# With background upscaling
gfpgan-infer --input photo.jpg --upscale 2 --bg_upsampler realesrgan

Advanced options

# Dry run to validate settings
gfpgan-infer --input photos/ --dry-run

# CPU-only mode
gfpgan-infer --input photo.jpg --device cpu

# Disable background upsampling for speed
gfpgan-infer --input photo.jpg --bg_upsampler none

Performance hints (optional)

Both CLIs accept safe-by-default performance hints:

These degrade gracefully when unsupported on your hardware.

Plugin backends

You can extend backends via Python entry points with the group gfpp.restorers mapping name -> module:Class. Discovered plugins are merged with built-ins and errors are isolated.

Web interface

Launch the interactive web UI:

# Basic interface
python -m gfpgan.gradio_app

# API server
uvicorn services.api.main:app --reload

Model comparison

Model Speed Quality Identity Preservation Best For
GFPGAN v1.3 Medium High Good Natural results (recommended)
GFPGAN v1.2 Medium High Good Sharp output with beauty makeup
GFPGAN v1 Medium Medium Fair Basic restoration with colorization
RestoreFormerPlusPlus Slow Highest Excellent Professional work, TPAMI 2023 version
RestoreFormer Slow High Excellent High-quality restoration
CodeFormer Fast Medium Good AI-generated faces, batch processing
CodeFormerColorization Fast Medium Good Specialized for colorization tasks
CodeFormerInpainting Fast Medium Good Face inpainting and completion

Choose your model with --version flag: 1.3 (default), 1.2, 1, RestoreFormerPlusPlus, RestoreFormer, CodeFormer, CodeFormerColorization, or CodeFormerInpainting.

Contributing

We welcome contributions! Please see our contributing guide for:

Security

Found a security issue? Please report it privately via our security policy.

License and acknowledgements

GFPGAN is released under the Apache License 2.0. See LICENSE for details.

Acknowledgements

This project builds upon the foundational research and implementations from:

Note: This project has been completely unforked from TencentARC/GFPGAN and now operates independently. Models are automatically downloaded from their official sources: TencentARC/GFPGAN releases, sczhou/CodeFormer releases, and Hugging Face Hub for legacy models.

For a complete list of dependencies and their licenses, see LICENSES/.

Citation

If you use GFPGAN in your research, please cite:

@InProceedings{wang2021gfpgan,
    author = {Xintao Wang and Yu Li and Honglun Zhang and Ying Shan},
    title = {Towards Real-World Blind Face Restoration with Generative Facial Prior},
    booktitle = {The IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
    year = {2021}
}

Questions? Check our FAQ • Documentation • Issues

This site is open source. Improve this page.