Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 92.2s
py 3.11
✕ build_error
✓ 87.4s
py 3.12
✕ build_error
✓ 80.8s
py 3.13
✕ build_error
✓ 73.9s
py 3.9
✕ build_error
✕ timeout
5453MB installed
● package 5453MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FaceRestoreHelper
✓ from facexlib.utils.face_restoration_helper import FaceRestoreHelper
This is the main helper class for face restoration pipelines.
init_detection_model
✓ from facexlib.detection import init_detection_model
Used to initialize various face detection models.
init_parsing_model
✓ from facexlib.parsing import init_parsing_model
Used to initialize face parsing models.
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.
import numpy as np
import cv2
from facexlib.utils.face_restoration_helper import FaceRestoreHelper
# Create a dummy image (e.g., a black square)
img = np.zeros((512, 512, 3), dtype=np.uint8)
# Add a white square to simulate a face for detection
img[200:300, 200:300] = 255
# Initialize FaceRestoreHelper
# upscale_factor: The factor to upscale the face. Set to 1 if no upscale needed
# det_model: The detection model to use, e.g., 'retinaface_resnet50' or 'retinaface_mobile0.25'
# device: 'cuda' or 'cpu'
face_helper = FaceRestoreHelper(upscale_factor=1, det_model='retinaface_resnet50', device='cpu')
# Read the image (can also be a path)
face_helper.read_image(img)
# Detect and align faces
# save_cropped_path: Optional path to save cropped faces
face_helper.get_face_landmarks_5(only_keep_largest=True)
face_helper.align_warp_face()
# Process the aligned faces (e.g., feed to a restoration model)
# This example just shows the aligned face
if len(face_helper.cropped_faces) > 0:
aligned_face = face_helper.cropped_faces[0]
print(f"Detected and aligned face of shape: {aligned_face.shape}")
# In a real scenario, you'd feed aligned_face to a restoration network
# For this quickstart, we'll just show its dimensions.
# cv2.imwrite('aligned_face.png', aligned_face) # Uncomment to save
else:
print("No faces detected in the image.")
# Clean up (release models if no longer needed)
del face_helper
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'facexlib'
The 'facexlib' library is not installed in the Python environment you are using, or the environment's paths are not correctly configured to find it. This is a common issue when running a project that depends on facexlib but the library itself hasn't been properly installed in the active environment.
fixInstall facexlib using pip: `pip install facexlib`. If you are in a specific virtual environment, ensure that environment is activated before running the install command. For some specific contexts like ComfyUI, you might need to use `python -m pip install --use-pep517 facexlib`.
AttributeError: 'numpy.ndarray' object has no attribute 'append'
This error typically occurs within `facexlib\utils\face_restoration_helper.py` when a variable expected to be a Python list (which has an `append` method) is inadvertently reassigned to a NumPy array, which does not have this method in the same way. It is often observed in multi-threaded contexts where `FaceRestoreHelper` is used without proper synchronization, leading to race conditions or incorrect state management.
fixIf using `FaceRestoreHelper` in a multi-threaded application, implement threading locks or semaphores around its usage to ensure thread-safety. Review the code to ensure that list-like objects are not being overwritten by NumPy arrays where an `append` operation is expected.
RuntimeError: facexlib align face fail
This indicates that the face detection or alignment algorithms within facexlib could not successfully process the input image. This typically happens when no faces are detected, faces are too small or too large, the face angle is too extreme, or the image quality is too low for the algorithm to work effectively.
fixImplement robust error handling (e.g., a try-except block) around calls to `facexlib`'s face alignment functions. Preprocess images to ensure they contain detectable faces of appropriate size and quality, and consider filtering out images where detection is unlikely to succeed. Check image dimensions and content before passing them to the face processing functions.
Cannot install on Python version X; only versions >=3.7,<3.11 are supported.
The Python version you are trying to install `facexlib` with is outside the range officially supported by the library or one of its dependencies. As of version 0.3.0, `facexlib` typically supports Python versions from 3.7 up to 3.10, and newer Python versions (like 3.11 or 3.12) might not be fully compatible, leading to installation failures often related to dependencies like `filterpy` or `numba`.
fixUse a compatible Python version for your development environment, typically Python 3.7 to 3.10. Consider using tools like `conda` or `pyenv` to manage multiple Python versions and create a virtual environment with a supported Python version for `facexlib`.
Upgrade
Version history
0.3.0latest on PyPI · released Apr 15, 2023
Audit
Dependencies
torchrequiredCore deep learning framework.
torchvisionrequiredRequired for vision-related functionalities.
opencv-pythonrequiredUsed for image processing and handling within the library.
numpyrequiredFundamental package for numerical operations.
pillowrequiredImage manipulation library, often used with vision tasks.
numbaoptionalOptional dependency for performance optimization.