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.920 runs
build_error
glibcpy 3.10–3.920 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GFPGANer
✓ from gfpgan import GFPGANer
✗ from gfpgan import GFPGANer
This quickstart demonstrates how to initialize the GFPGANer and enhance an image. Before running, you *must* manually download a pre-trained model checkpoint (e.g., `GFPGANv1.3.pth`) from the official GitHub releases and place it in the same directory as your script. The example code includes a dummy image for testing, but for real use, replace `input_img` with your actual image loaded via `cv2.imread`.
import cv2
import numpy as np
import os
from gfpgan import GFPGANer
# 1. Prepare a dummy input image
# In a real scenario, you would load your image: img = cv2.imread('path/to/your/image.jpg', cv2.IMREAD_COLOR)
# For a runnable example, create a 256x256 black image with some noise.
input_img = np.zeros((256, 256, 3), dtype=np.uint8)
noise = np.random.randint(-50, 50, (256, 256, 3), dtype=np.int16)
input_img = np.clip(input_img + noise, 0, 255).astype(np.uint8)
# 2. Download the pre-trained GFPGAN model
# GFPGAN models are NOT bundled with the pip package and must be downloaded manually.
# Download GFPGANv1.3.pth from: https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.3.pth
model_path = 'GFPGANv1.3.pth' # Place the downloaded model in the same directory as your script
if not os.path.exists(model_path):
print(f"Warning: Model file '{model_path}' not found. Please download it from:")
print(" https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.3.pth")
print(" Proceeding with a placeholder; actual enhancement will not occur without the model.")
enhanced_img = input_img.copy() # Fallback for quickstart if model not present
else:
# 3. Initialize GFPGANer
# Use 'cpu' for broad compatibility. Change to 'cuda' if a GPU is available.
restorer = GFPGANer(
model_path=model_path,
upscale=2, # Upscale factor: 1, 2, or 4
arch='clean', # Model architecture: 'original' or 'clean'
channel_multiplier=2,
bg_upsampler=None, # Set to 'realesrgan' if you want background upsampling
device='cpu' # 'cuda' for GPU, 'cpu' for CPU
)
# 4. Enhance the image
# The enhance method returns cropped_faces, restored_faces, and the final enhanced_img.
cropped_faces, restored_faces, enhanced_img = restorer.enhance(
input_img, # Input image (BGR format)
has_aligned=False, # Set to True if input faces are already aligned
only_center_face=False, # Set to True to only enhance the most prominent face
paste_back=True # Set to True to paste restored faces back into the original image
)
# 5. Save the output image
output_path = 'gfpgan_enhanced_output.jpg'
cv2.imwrite(output_path, enhanced_img)
print(f"Enhanced image (or original if model was missing) saved to {output_path}")
gfpgan --version
Upgrade
Version history
1.3.8latest on PyPI · released Sep 16, 2022
Audit
Dependencies
basicsrrequiredCore dependency for image restoration functionalities and base utilities.
facexlibrequiredUsed for face detection and parsing during the restoration process.
opencv-pythonrequiredRequired for image loading, processing, and saving (e.g., cv2.imread, cv2.imwrite).
numpyrequiredFundamental package for numerical operations, especially array handling for images.
PillowrequiredImage processing library, often used by other dependencies like torchvision.
torchrequiredThe underlying deep learning framework (PyTorch) is essential for model inference.
torchvisionrequiredPyTorch's vision library, providing dataset, models, and transformations for computer vision.