{"id":21317,"library":"face-alignment","title":"face_alignment","description":"Face alignment is a Python library for detecting 2D or 3D face landmarks from images. Current version 1.5.0 supports multiple detection models (SFD, BlazeFace, etc.) and landmark models (2D and 3D). Release cadence is irregular, with major updates every few months.","status":"active","version":"1.5.0","language":"python","source_language":"en","source_url":"https://github.com/1adrianb/face-alignment","tags":["face-alignment","landmarks","computer-vision","deep-learning","pytorch"],"install":[{"cmd":"pip install face-alignment","lang":"bash","label":"Default"},{"cmd":"pip install face-alignment --no-deps","lang":"bash","label":"No dependencies"}],"dependencies":[{"reason":"Deep learning framework for model inference.","package":"torch","optional":false},{"reason":"Array operations.","package":"numpy","optional":false},{"reason":"Image loading and processing.","package":"opencv-python","optional":false},{"reason":"Image transformation utilities.","package":"scikit-image","optional":false}],"imports":[{"note":"The class is not the module; must import explicitly.","wrong":"import face_alignment","symbol":"FaceAlignment","correct":"from face_alignment import FaceAlignment"},{"note":"","wrong":"","symbol":"LandmarksType","correct":"from face_alignment import LandmarksType"},{"note":"","wrong":"","symbol":"NetworkSize","correct":"from face_alignment import NetworkSize"}],"quickstart":{"code":"import cv2\nfrom face_alignment import FaceAlignment, LandmarksType, NetworkSize\n\nfa = FaceAlignment(LandmarksType.TWO_D, network_size=NetworkSize.LARGE)\nimg = cv2.imread('input.jpg')\npreds = fa.get_landmarks(img)\nprint(preds)","lang":"python","description":"Load an image, run face alignment, and print 2D landmarks."},"warnings":[{"fix":"Upgrade Python to 3.8+ and PyTorch to 1.12+.","message":"In v1.5.0, support for Python <3.8 and PyTorch <1.12 is dropped. Older installations may fail.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Ensure internet access or pre-download models by running once.","message":"The package no longer ships with bundled model weights; models are downloaded via torch.hub on first use. This requires an internet connection.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Always check: if preds is not None: ...","message":"FaceAlignment.get_landmarks() returns None if no face is detected, not an empty list. Iterating over None will cause TypeError.","severity":"gotcha","affected_versions":"all"},{"fix":"Install via pip install face-alignment.","message":"The conda package is no longer maintained. Use pip instead.","severity":"deprecated","affected_versions":">=1.5.0"},{"fix":"If landmarks are inaccurate, convert image: img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB).","message":"The library expects images in BGR format (OpenCV default), but the detection model may expect RGB. Inconsistent behavior across versions.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"pip install face-alignment","cause":"Package not installed or installed with wrong name.","error":"ModuleNotFoundError: No module named 'face_alignment'"},{"fix":"Check: if preds is not None: ...","cause":"get_landmarks returned None because no face detected.","error":"TypeError: 'NoneType' object is not iterable"},{"fix":"Run once with internet, or manually download from torch.hub.","cause":"Missing model weights; network issue prevented download.","error":"RuntimeError: Model not found. Please download the model first."},{"fix":"Use: from face_alignment import FaceAlignment","cause":"Wrong import statement: import face_alignment instead of from face_alignment import FaceAlignment.","error":"AttributeError: module 'face_alignment' has no attribute 'FaceAlignment'"},{"fix":"Use NetworkSize.LARGE or NetworkSize.LARGE2 (4GB+ VRAM) as appropriate.","cause":"Incorrect NetworkSize argument.","error":"ValueError: Cannot load model with given network size"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}