{"id":7258,"library":"gfpgan","title":"GFPGAN: Real-world Face Restoration","description":"GFPGAN (Generative Facial Prior-guided Face Restoration) is a Python library that provides practical algorithms for high-quality face restoration, especially for degraded real-world images. It leverages a pre-trained GAN (Generative Adversarial Network) as a facial prior for robust restoration. The current version is 1.3.8, with a history of frequent minor updates addressing bugs, adding features, and refining model architectures.","status":"active","version":"1.3.8","language":"python","source_language":"en","source_url":"https://github.com/TencentARC/GFPGAN","tags":["image-processing","face-restoration","deep-learning","computer-vision","generative-ai"],"install":[{"cmd":"pip install gfpgan","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for image restoration functionalities and base utilities.","package":"basicsr"},{"reason":"Used for face detection and parsing during the restoration process.","package":"facexlib"},{"reason":"Required for image loading, processing, and saving (e.g., cv2.imread, cv2.imwrite).","package":"opencv-python"},{"reason":"Fundamental package for numerical operations, especially array handling for images.","package":"numpy"},{"reason":"Image processing library, often used by other dependencies like torchvision.","package":"Pillow"},{"reason":"The underlying deep learning framework (PyTorch) is essential for model inference.","package":"torch"},{"reason":"PyTorch's vision library, providing dataset, models, and transformations for computer vision.","package":"torchvision"}],"imports":[{"wrong":"from gfpgan import GFPGANer","symbol":"GFPGANer","correct":"from gfpgan import GFPGANer"}],"quickstart":{"code":"import cv2\nimport numpy as np\nimport os\nfrom gfpgan import GFPGANer\n\n# 1. Prepare a dummy input image\n# In a real scenario, you would load your image: img = cv2.imread('path/to/your/image.jpg', cv2.IMREAD_COLOR)\n# For a runnable example, create a 256x256 black image with some noise.\ninput_img = np.zeros((256, 256, 3), dtype=np.uint8)\nnoise = np.random.randint(-50, 50, (256, 256, 3), dtype=np.int16)\ninput_img = np.clip(input_img + noise, 0, 255).astype(np.uint8)\n\n# 2. Download the pre-trained GFPGAN model\n# GFPGAN models are NOT bundled with the pip package and must be downloaded manually.\n# Download GFPGANv1.3.pth from: https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.3.pth\nmodel_path = 'GFPGANv1.3.pth' # Place the downloaded model in the same directory as your script\n\nif not os.path.exists(model_path):\n print(f\"Warning: Model file '{model_path}' not found. Please download it from:\")\n print(\" https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.3.pth\")\n print(\" Proceeding with a placeholder; actual enhancement will not occur without the model.\")\n enhanced_img = input_img.copy() # Fallback for quickstart if model not present\nelse:\n # 3. Initialize GFPGANer\n # Use 'cpu' for broad compatibility. Change to 'cuda' if a GPU is available.\n restorer = GFPGANer(\n model_path=model_path,\n upscale=2, # Upscale factor: 1, 2, or 4\n arch='clean', # Model architecture: 'original' or 'clean'\n channel_multiplier=2,\n bg_upsampler=None, # Set to 'realesrgan' if you want background upsampling\n device='cpu' # 'cuda' for GPU, 'cpu' for CPU\n )\n\n # 4. Enhance the image\n # The enhance method returns cropped_faces, restored_faces, and the final enhanced_img.\n cropped_faces, restored_faces, enhanced_img = restorer.enhance(\n input_img, # Input image (BGR format)\n has_aligned=False, # Set to True if input faces are already aligned\n only_center_face=False, # Set to True to only enhance the most prominent face\n paste_back=True # Set to True to paste restored faces back into the original image\n )\n\n# 5. Save the output image\noutput_path = 'gfpgan_enhanced_output.jpg'\ncv2.imwrite(output_path, enhanced_img)\nprint(f\"Enhanced image (or original if model was missing) saved to {output_path}\")\n","lang":"python","description":"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`."},"warnings":[{"fix":"Downgrade to GFPGAN v1.3.7 or earlier if `codeformer` functionality is essential. Alternatively, adapt your workflow to use other available components or remove `codeformer`-specific calls.","message":"The `codeformer` integration was removed in GFPGAN v1.3.8. If your code relied on this component, it will break or require modification.","severity":"breaking","affected_versions":">=1.3.8"},{"fix":"Always download the required `.pth` model file (e.g., GFPGANv1.3.pth) from the official GitHub releases and provide its path to the `GFPGANer` constructor.","message":"GFPGAN models (e.g., `GFPGANv1.3.pth`) are not bundled with the pip package and must be manually downloaded from the official GitHub releases page. The library will not function without a valid model path.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure PyTorch is installed correctly for your specific hardware (CPU or GPU) and CUDA version. Refer to the official PyTorch installation instructions for your system. Specify `device='cuda'` in `GFPGANer` if you have a compatible GPU.","message":"GFPGAN relies on PyTorch and potentially CUDA for optimal performance. Incorrect PyTorch/CUDA installation or version mismatches can lead to runtime errors or force CPU-only processing.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid using GFPGAN v1.3.0. Upgrade to v1.3.1 or a later version to resolve import issues.","message":"An `ImportError` was present in v1.3.0 due to a missing file. While fixed in v1.3.1, this highlights potential instability in specific minor point releases.","severity":"breaking","affected_versions":"1.3.0"}],"env_vars":null,"search_vec":"'1.3.8':57 'ad':67 'address':65 'adversari':44 'ai':87 'algorithm':22 'architectur':72 'bug':66 'comput':83 'computer-vis':82 'current':54 'deep':80 'deep-learn':79 'degrad':31 'especi':29 'face':5,13,27,77 'face-restor':76 'facial':9,48 'featur':68 'frequent':62 'gan':42 'generat':8,43,86 'generative-ai':85 'gfpgan':1,7 'guid':12 'high':25 'high-qual':24 'histori':60 'imag':35,74 'image-process':73 'learn':81 'leverag':37 'librari':18 'minor':63 'model':71 'network':45 'practic':21 'pre':40 'pre-train':39 'prior':11,49 'prior-guid':10 'process':75 'provid':20 'python':17 'qualiti':26 'real':3,33 'real-world':2,32 'refin':70 'restor':6,14,28,52,78 'robust':51 'train':41 'updat':64 'version':55 'vision':84 'world':4,34","created_at":"2026-04-16T13:50:32.357144+00:00","updated_at":"2026-04-16T13:50:32.357144+00:00","problems":{"verify_error":"Traceback (most recent call last):\n File \"\", line 1, in \n File \"/tmp/tmprglf4zz0/venv/lib/python3.12/site-packages/gfpgan/__init__.py\", line 2, in \n from .archs import *\n File \"/tmp/tmprglf4zz0/venv/lib/python3.12/site-packages/gfpgan/archs/__init__.py\", line 2, in