# How to Fix Common Dlib Installation Errors in Face Recognition Projects

> Fix dlib installation errors for face recognition projects. Learn to resolve missing bindings outdated versions CPU mismatches and compilation issues.

- Repository: [Adam Geitgey/face_recognition](https://github.com/ageitgey/face_recognition)
- Tags: how-to-guide
- Published: 2026-03-06

---

**Most dlib installation errors in the face_recognition library stem from missing Python bindings, outdated versions (<19.7), or CPU instruction set mismatches, and can be resolved by installing from source, upgrading via pip, or disabling AVX/SSE flags during compilation.**

The `face_recognition` library relies on the C++-based **dlib** library for face detection, pose prediction, and 128-dimensional face encoding. Because `face_recognition` imports dlib at runtime via `import dlib` in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py) (line 4), any compilation failure or version mismatch prevents the entire package from loading. This guide covers the most common dlib installation errors and provides repository-tested fixes.

## Common Dlib Installation Errors and Solutions

### ImportError: No module named dlib

This error occurs when the Python bindings for dlib are missing entirely. According to the installation steps in `README.rst` (lines 99-103), dlib must be installed **before** attempting to install `face_recognition`.

**Fix:**

Install dlib from source on macOS or Ubuntu following the official gist referenced in the repository:

```bash

# Ubuntu dependencies

sudo apt-get update && sudo apt-get install -y build-essential cmake libopenblas-dev liblapack-dev \
    libboost-python-dev libboost-thread-dev

# macOS dependencies

# brew install cmake boost

# Install dlib

pip install dlib

```

### AttributeError: module 'dlib' has no attribute 'face_recognition_model_v1'

If you encounter `AttributeError: module 'dlib' has no attribute 'face_recognition_model_v1'` or `cnn_face_detection_model_v1`, your dlib version is older than the minimum required 19.7. The `face_recognition` API relies on these specific dlib model loaders defined in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py).

**Fix:**

Upgrade dlib to version 19.7 or newer:

```bash
pip install --upgrade "dlib>=19.7"

```

If pip wheels are unavailable for your platform, rebuild from source after cloning the dlib repository.

### Illegal instruction (core dumped)

This error indicates that dlib was compiled with **SSE4** or **AVX** CPU instructions that your hardware does not support. As documented in `README.rst` (lines 180-185), this typically happens when installing pre-compiled binaries on older CPUs or virtual machines with limited instruction sets.

**Fix:**

Recompile dlib without AVX/SSE optimizations. Clone the dlib source and build with flags disabled:

```bash
git clone https://github.com/davisking/dlib.git
cd dlib
export DLIB_NO_AVX=1
python setup.py install --no USE_AVX_INSTRUCTIONS

```

Alternatively, set the environment variable `CFLAGS="-march=core2"` before pip install to force generic x86-64 instructions compatible with older processors.

### RuntimeError: Unsupported image type

While not strictly a compilation error, `RuntimeError: Unsupported image type, must be 8-bit gray or RGB image` often appears when dlib receives improperly formatted input from OpenCV. This occurs when OpenCV is not correctly installed or when webcam frames are not converted to the expected format, as noted in `README.rst` (lines 267-270).

**Fix:**

Ensure OpenCV is correctly installed and convert images to RGB before passing to face_recognition:

```python
import cv2
import face_recognition

# Load with OpenCV (BGR format)

image = cv2.imread("photo.jpg")

# Convert to RGB for dlib

rgb_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)

# Now safe to use

locations = face_recognition.face_locations(rgb_image)

```

### MemoryError during pip install

When installing `face_recognition` via pip, you may encounter `MemoryError` during the download phase. This happens because the large pre-trained model files exhaust pip's cache memory, as noted in `README.rst` (lines 334-339).

**Fix:**

Install without caching:

```bash
pip install --no-cache-dir face_recognition

```

## Step-by-Step Dlib Installation Verification

After applying any fix, verify your installation using the actual API calls from [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py):

```python
import dlib
import face_recognition

# Check dlib version (must be >= 19.7)

print("dlib version:", dlib.__version__)

# Test face detection (uses get_frontal_face_detector from api.py)

image = face_recognition.load_image_file("examples/obama.jpg")
locations = face_recognition.face_locations(image)
print("Detected faces:", len(locations))

```

If this script runs without `ImportError`, `AttributeError`, or `Illegal instruction`, your dlib installation is correctly configured for the face_recognition library.

## Summary

- **Install dlib first** before attempting to install `face_recognition`, following the macOS/Ubuntu source compilation guide or using a pre-built Windows wheel.
- **Ensure dlib >= 19.7** to avoid `AttributeError` for missing model loaders like `face_recognition_model_v1`.
- **Recompile without AVX/SSE** if you encounter "Illegal instruction" errors on older CPUs or virtual machines.
- **Use `--no-cache-dir`** when pip runs out of memory downloading large model files.
- **Verify with a test script** importing both `dlib` and `face_recognition` and running `face_locations` on a sample image.

## Frequently Asked Questions

### Why does face_recognition fail to import even after pip install?

The `face_recognition` library imports `dlib` at the module level in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py) (line 4). If dlib isn't installed or is compiled incorrectly, Python raises an `ImportError` before any face_recognition code runs. Install dlib separately and verify with `import dlib` before installing face_recognition.

### How do I fix "Illegal instruction (core dumped)" when importing dlib?

This error occurs when dlib is compiled with AVX or SSE4 instructions that your CPU doesn't support. Clone the dlib source repository and rebuild with CPU-specific optimizations disabled: `export DLIB_NO_AVX=1` or `python setup.py install --no USE_AVX_INSTRUCTIONS`. This generates generic x86-64 code compatible with older processors.

### What is the minimum dlib version required for face_recognition?

The `face_recognition` library requires **dlib 19.7 or newer**. Earlier versions lack the `face_recognition_model_v1` and `cnn_face_detection_model_v1` functions used in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py). Check your version with `print(dlib.__version__)` and upgrade via `pip install --upgrade "dlib>=19.7"` if necessary.

### Can I use face_recognition on Windows without compiling dlib?

Yes, you can avoid compilation on Windows by installing a pre-built binary wheel for dlib. Download a wheel matching your Python version from PyPI or community repositories, then install with `pip install dlib‑19.19.0‑cp39‑cp39‑win_amd64.whl` (adjusting for your specific Python version). This bypasses the need for CMake, Boost, and Visual Studio toolchains.