{"id":3996,"library":"facexlib","title":"FaceXlib: Basic Face Library","description":"FaceXlib is a Python library providing ready-to-use face-related functions based on state-of-the-art open-source methods, including detection, alignment, recognition, parsing, and restoration. It is currently at version 0.3.0 and has an active, though somewhat irregular, release cadence with recent updates focusing on stability and functionality improvements.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/xinntao/facexlib","tags":["face detection","face restoration","computer vision","deep learning","pytorch","image processing","face alignment","face parsing"],"install":[{"cmd":"pip install facexlib","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core deep learning framework.","package":"torch","optional":false},{"reason":"Required for vision-related functionalities.","package":"torchvision","optional":false},{"reason":"Used for image processing and handling within the library.","package":"opencv-python","optional":false},{"reason":"Fundamental package for numerical operations.","package":"numpy","optional":false},{"reason":"Image manipulation library, often used with vision tasks.","package":"pillow","optional":false},{"reason":"Optional dependency for performance optimization.","package":"numba","optional":true}],"imports":[{"note":"This is the main helper class for face restoration pipelines.","symbol":"FaceRestoreHelper","correct":"from facexlib.utils.face_restoration_helper import FaceRestoreHelper"},{"note":"Used to initialize various face detection models.","symbol":"init_detection_model","correct":"from facexlib.detection import init_detection_model"},{"note":"Used to initialize face parsing models.","symbol":"init_parsing_model","correct":"from facexlib.parsing import init_parsing_model"}],"quickstart":{"code":"import numpy as np\nimport cv2\nfrom facexlib.utils.face_restoration_helper import FaceRestoreHelper\n\n# Create a dummy image (e.g., a black square)\nimg = np.zeros((512, 512, 3), dtype=np.uint8)\n# Add a white square to simulate a face for detection\nimg[200:300, 200:300] = 255\n\n# Initialize FaceRestoreHelper\n# upscale_factor: The factor to upscale the face. Set to 1 if no upscale needed\n# det_model: The detection model to use, e.g., 'retinaface_resnet50' or 'retinaface_mobile0.25'\n# device: 'cuda' or 'cpu'\nface_helper = FaceRestoreHelper(upscale_factor=1, det_model='retinaface_resnet50', device='cpu')\n\n# Read the image (can also be a path)\nface_helper.read_image(img)\n\n# Detect and align faces\n# save_cropped_path: Optional path to save cropped faces\nface_helper.get_face_landmarks_5(only_keep_largest=True)\nface_helper.align_warp_face()\n\n# Process the aligned faces (e.g., feed to a restoration model)\n# This example just shows the aligned face\nif len(face_helper.cropped_faces) > 0:\n    aligned_face = face_helper.cropped_faces[0]\n    print(f\"Detected and aligned face of shape: {aligned_face.shape}\")\n    # In a real scenario, you'd feed aligned_face to a restoration network\n    # For this quickstart, we'll just show its dimensions.\n    # cv2.imwrite('aligned_face.png', aligned_face) # Uncomment to save\nelse:\n    print(\"No faces detected in the image.\")\n\n# Clean up (release models if no longer needed)\ndel face_helper\n","lang":"python","description":"This quickstart demonstrates how to initialize the `FaceRestoreHelper`, read an image (dummy in this case), detect and align faces. It highlights the basic workflow, where detected and aligned faces would typically be fed into a specialized face restoration or processing model. Model weights are downloaded automatically on first inference."},"warnings":[{"fix":"Manually download pre-trained models and place them in `PACKAGE_ROOT_PATH/facexlib/weights` as described in the official documentation.","message":"Pre-trained models are downloaded automatically on the first inference. Users with unstable network connections may experience issues. It's recommended to pre-download models if connectivity is a concern.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your environment or code explicitly sets `model_rootpath` in helper constructors or verify that `facexlib` can access/create its new default model cache location.","message":"Starting from v0.2.5, the library changed the default model root path to save models, so `facexlib` no longer strictly requires saving models in the `site-packages` directory. This might affect existing setups that relied on the old implicit path.","severity":"breaking","affected_versions":"Prior to v0.2.5"},{"fix":"If using an older version on CPU, explicitly set `device='cpu'` in the `FaceRestoreHelper` constructor or upgrade to v0.2.5 or newer for guaranteed CPU support.","message":"Prior to v0.2.5, `FaceRestoreHelper` might have implicitly required GPU for operation. CPU-only usage was explicitly supported from v0.2.5 onwards.","severity":"gotcha","affected_versions":"Prior to v0.2.5"},{"fix":"Be aware of potential minor changes in face alignment if precise reproducibility across versions is critical. Update and re-evaluate results if necessary.","message":"Version v0.2.2 updated the `cv2.estimateAffinePartial2D` method to use `cv2.LMEDS` for affine transformation estimation. This change aims for equivalence with skimage transform but might lead to subtle differences in face alignment results compared to earlier versions.","severity":"gotcha","affected_versions":"Prior to v0.2.2"},{"fix":"Verify that `facexlib` is installed in the active Python environment (e.g., `pip list | grep facexlib`). Ensure your IDE or script uses the correct Python interpreter where `facexlib` is installed. Reinstalling within a clean virtual environment often resolves such issues.","message":"Users sometimes encounter `ModuleNotFoundError: No module named 'facexlib'` even after installation, indicating potential environment or installation issues.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}