{"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":"en","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":[{"note":"GFPGANer is the main class for initializing the restorer and performing enhancement.","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,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"If `codeformer` is essential, downgrade to GFPGAN v1.3.7 or earlier (`pip install gfpgan==1.3.7`). Otherwise, remove any code references to `codeformer` components.","cause":"This module was removed in GFPGAN v1.3.8, leading to a `ModuleNotFoundError` if your code attempts to import or use `codeformer_arch`.","error":"ModuleNotFoundError: No module named 'gfpgan.archs.codeformer_arch'"},{"fix":"Download the required `.pth` model file (e.g., GFPGANv1.3.pth) from the official GitHub releases (https://github.com/TencentARC/GFPGAN/releases) and ensure its path is correctly provided to the `GFPGANer` constructor.","cause":"The specified model file (e.g., 'GFPGANv1.3.pth') could not be found. GFPGAN models are not installed with the pip package.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'GFPGANv1.3.pth'"},{"fix":"Verify your PyTorch and CUDA installations. Ensure your `device` parameter in `GFPGANer` is set correctly (e.g., `device='cuda'` if a GPU is present, otherwise `device='cpu'`). Check `torch.cuda.is_available()` and `torch.cuda.device_count()`.","cause":"This typically indicates an issue with PyTorch's CUDA setup, such as attempting to use a GPU device that doesn't exist, is out of range, or CUDA drivers are not properly configured.","error":"RuntimeError: CUDA error: invalid device ordinal"},{"fix":"Ensure `basicsr` is installed: `pip install basicsr`. If you installed `gfpgan` via `pip`, `basicsr` should have been installed automatically; check your environment and Python path.","cause":"`basicsr` is a core dependency for GFPGAN, and this error indicates it was not installed or is not accessible in the current environment.","error":"ModuleNotFoundError: No module named 'basicsr'"}]}