{"id":5195,"library":"dlib","title":"dlib - Machine Learning Toolkit","description":"dlib is a modern C++ toolkit that provides a wide array of machine learning algorithms and tools, exposed via a Python API. It is widely used for computer vision tasks such as state-of-the-art facial recognition, object detection, and image processing, as well as general machine learning applications including SVMs, clustering, and regression. The library is actively maintained, with frequent patch releases and occasional minor or major version bumps, the current version being 20.0.1.","status":"active","version":"20.0.1","language":"en","source_language":"en","source_url":"https://github.com/davisking/dlib","tags":["machine-learning","computer-vision","facial-recognition","object-detection","image-processing","cpp-bindings"],"install":[{"cmd":"pip install dlib","lang":"bash","label":"Basic Install"}],"dependencies":[{"reason":"Required for building the package, typically handled by pip.","package":"setuptools","optional":false}],"imports":[{"note":"The primary import for accessing all dlib functionalities.","symbol":"dlib","correct":"import dlib"},{"symbol":"get_frontal_face_detector","correct":"detector = dlib.get_frontal_face_detector()"},{"symbol":"shape_predictor","correct":"predictor = dlib.shape_predictor('model.dat')"}],"quickstart":{"code":"import dlib\nimport numpy as np # Used for dummy image\n\n# --- Quickstart: Face Detection and Landmark Prediction API Usage ---\n# Note: For this example to produce meaningful results, you need:\n# 1. A pre-trained facial landmark predictor model file (e.g., 'shape_predictor_68_face_landmarks.dat').\n#    Download from: http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2\n#    Then decompress it using 'bunzip2'.\n# 2. An actual image file. Replace 'path/to/your/image.jpg' below.\n\n# --- 1. Face Detection ---\n# Initialize the frontal face detector\ndetector = dlib.get_frontal_face_detector()\n\n# Load an image (replace with your actual image file path)\n# For demonstration, we use a placeholder:\ntry:\n    img = dlib.load_rgb_image(\"path/to/your/image.jpg\")\nexcept RuntimeError:\n    print(\"Warning: Could not load dummy image 'path/to/your/image.jpg'.\")\n    print(\"Using a blank NumPy array for demonstration purposes. Face detection will likely find nothing.\")\n    img = np.zeros((400, 400, 3), dtype=np.uint8) # Create a 400x400 black image\n\n# Detect faces in the image. The '1' argument means to upsample the image 1 time\n# (make it larger) to find smaller faces.\ndets = detector(img, 1)\nprint(f\"Detected {len(dets)} faces (or regions of interest) in the image.\")\n\n# --- 2. Facial Landmark Prediction ---\n# Initialize the shape predictor (requires a downloaded model file)\nmodel_path = \"shape_predictor_68_face_landmarks.dat\" # Replace with actual path\ntry:\n    predictor = dlib.shape_predictor(model_path)\nexcept dlib.set_level_error as e:\n    print(f\"Error: Could not load shape predictor model from '{model_path}'.\")\n    print(\"Please download 'shape_predictor_68_face_landmarks.dat' and provide the correct path.\")\n    predictor = None # Prevent further errors if model loading failed\n\nif predictor:\n    for i, d in enumerate(dets):\n        # Predict landmarks for each detected face\n        print(f\"  Processing face {i+1} at bounding box: Left: {d.left()}, Top: {d.top()}, Right: {d.right()}, Bottom: {d.bottom()}\")\n        try:\n            shape = predictor(img, d)\n            print(f\"  Found {shape.num_parts} facial landmarks for face {i+1}.\")\n            if shape.num_parts > 0:\n                print(f\"  Example: First landmark point: ({shape.part(0).x}, {shape.part(0).y})\")\n        except Exception as e:\n            print(f\"  Could not find landmarks for face {i+1}. This is expected if the image is blank or model is incorrect. Error: {e}\")\nelse:\n    print(\"Skipping facial landmark prediction due to missing or invalid model.\")\n\nprint(\"\\ndlib quickstart example finished.\")","lang":"python","description":"Demonstrates how to use dlib for frontal face detection and facial landmark prediction. Note that for meaningful results, you must provide a real image and download a pre-trained shape predictor model file separately, as these are not bundled with the pip package. The example includes error handling for missing files."},"warnings":[{"fix":"Update import paths (e.g., for `fhog_object_detector`) and replace `num_threads` arguments with calls to `dlib.set_thread_pool_size()` or remove them if global threading is acceptable.","message":"Version 20.0 introduced several breaking changes. `dlib.fhog_object_detector` was moved to `dlib.image_processing.fhog_object_detector`. The `num_threads` argument was removed from `train_shape_predictor` and `train_object_detector`, which now use the global dlib thread pool configurable via `dlib.set_thread_pool_size()`.","severity":"breaking","affected_versions":">=20.0"},{"fix":"Ensure you have C++ build tools (e.g., Visual C++ Build Tools on Windows, `build-essential` on Linux) along with CMake and Boost development headers (e.g., `libboost-python-dev`, `libboost-all-dev` on Linux) installed before attempting `pip install dlib`.","message":"Installation via `pip install dlib` often requires system-level prerequisites for compilation (C++ compiler, CMake, Boost development libraries). Pre-built wheels are not available for all platforms/Python versions, leading to a source build.","severity":"gotcha","affected_versions":"all"},{"fix":"Download the required `.dat` model files (often distributed as `.bz2` archives) from the official dlib website and provide the correct local path to functions like `dlib.shape_predictor()`.","message":"Pre-trained models (e.g., for facial landmarks, object detection) are not included in the pip package and must be downloaded manually from dlib's website (dlib.net/files) before use. Attempting to initialize predictors without the model file will result in runtime errors.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}