demo

In this article, we’ll guide you through the process of developing a face recognition app using the face_recognition package and Streamlit. We’ll demonstrate how to create an application that can detect faces in images, provide detailed instructions on resolving face_recognition installation issues, and offer a step-by-step guide for deploying your app to the cloud. Whether you’re a beginner or an experienced developer, this comprehensive tutorial will equip you with the knowledge to build and deploy your own face detection application.

If you want to see the app up and running, skip to the deployment section.

face_recognition installation challenges

face_recognition is a powerful and user-friendly Python library for facial recognition and manipulation. Built on top of dlib’s state-of-the-art face recognition algorithms, it provides a simple interface for detecting faces, finding facial features, and comparing faces across images. The library uses deep learning techniques to achieve high accuracy in face detection and recognition tasks. It can identify and manipulate facial features in images, making it ideal for various applications such as security systems, photo organization, and interactive user experiences.

One of the main challenges when working with face_recognition is its complex installation process. The library’s dependency on dlib, which is written in C++, introduces several prerequisites. Users must have a C++ compiler (typically g++) and CMake installed on their system before they can successfully install face_recognition. This requirement can be particularly daunting for users who are not familiar compiling C++ code or managing build tools. Additionally, face_recognition relies on pre-trained models from the face_recognition_models package, which comes with its own set of installation challenges. However, this guide will provide detailed instructions for a successful deployment

Installing dependencies

In this guide, we’ll demonstrate how to get the face recognition app working using Docker. Using Docker is an excellent approach for several reasons. It ensures a consistent development environment across different machines, simplifies the installation process by encapsulating all dependencies, and makes deployment more straightforward. By containerizing our application, we can avoid many of the common installation pitfalls associated with the face_recognition library and its dependencies, making it easier for others to run and deploy our face detection app. Source code available on GitHub.

At the top of the Dockerfile, we set the base image we’ll use. In our case, we’ll be using an image that has Python 3.11 installed. We chose this image because face_recognition is not compatible with Python 3.12 and newer versions.

FROM python:3.11-slim

Then, we need to install a few dependncies: cmake, and g++, which will help us compile dlib (a library that face_recognition uses under the hood). We also need to install git to install the face_recognition_models package.

RUN apt-get update && apt install cmake g++ git -y \
    && rm -rf /var/lib/apt/lists/*

The rest of the Dockerfile installs our application dependencies. In our case, we only need Streamlit, face_recognition, and face_recognition_models, but you can modify it if you need other packages. Finally, we start our streamlit app.

WORKDIR /app

COPY requirements.txt /app/requirements.txt
RUN pip install -r requirements.txt

COPY . /app

ENTRYPOINT ["streamlit", "run", "app.py", \
            "--server.port=80", \
            "--server.headless=true", \
            "--server.address=0.0.0.0", \
            "--browser.gatherUsageStats=false", \
            "--server.enableStaticServing=true", \
            "--server.fileWatcherType=none", \
            # hide the Streamlit menu
            "--client.toolbarMode=viewer"]

Troubleshooting installation

Error: CMake is not installed on your system!

Click to see the full CMake error

Collecting face_recognition
Downloading face_recognition-1.3.0-py2.py3-none-any.whl.metadata (21 kB)
Collecting face-recognition-models>=0.3.0 (from face_recognition)
Downloading face_recognition_models-0.3.0.tar.gz (100.1 MB)
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.1/100.1 MB 9.7 MB/s eta 0:00:00
Preparing metadata (setup.py) ... done
Collecting Click>=6.0 (from face_recognition)
Downloading click-8.1.7-py3-none-any.whl.metadata (3.0 kB)
Collecting dlib>=19.7 (from face_recognition)
Downloading dlib-19.24.6.tar.gz (3.4 MB)
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.4/3.4 MB 16.9 MB/s eta 0:00:00
Preparing metadata (setup.py) ... done
Collecting numpy (from face_recognition)
Downloading numpy-2.1.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.metadata (62 kB)
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 62.0/62.0 kB 7.3 MB/s eta 0:00:00
Collecting Pillow (from face_recognition)
Downloading pillow-10.4.0-cp311-cp311-manylinux_2_28_aarch64.whl.metadata (9.2 kB)
Downloading face_recognition-1.3.0-py2.py3-none-any.whl (15 kB)
Downloading click-8.1.7-py3-none-any.whl (97 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 97.9/97.9 kB 18.8 MB/s eta 0:00:00
Downloading numpy-2.1.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (14.0 MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 14.0/14.0 MB 16.9 MB/s eta 0:00:00
Downloading pillow-10.4.0-cp311-cp311-manylinux_2_28_aarch64.whl (4.4 MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.4/4.4 MB 17.0 MB/s eta 0:00:00
Building wheels for collected packages: dlib, face-recognition-models
Building wheel for dlib (setup.py) ... error
error: subprocess-exited-with-error

× python setup.py bdist_wheel did not run successfully.
│ exit code: 1
╰─> [41 lines of output]
running bdist_wheel
running build
running build_ext


================================================================================
================================================================================
================================================================================

                    CMake is not installed on your system!

    Or it is possible some broken copy of cmake is installed on your system.
    It is unfortunately very common for python package managers to include
    broken copies of cmake.  So if the error above this refers to some file
    path to a cmake file inside a python or anaconda or miniconda path then you
    should delete that broken copy of cmake from your computer.

    Instead, please get an official copy of cmake from one of these known good
    sources of an official cmake:
        - cmake.org (this is how windows users should get cmake)
        - apt install cmake (for Ubuntu or Debian based systems)
        - yum install cmake (for Redhat or CenOS based systems)

    On a linux machine you can run `which cmake` to see what cmake you are
    actually using.  If it tells you it's some cmake from any kind of python
    packager delete it and install an official cmake.

    More generally, cmake is not installed if when you open a terminal window
    and type
        cmake --version
    you get an error.  So you can use that as a very basic test to see if you
    have cmake installed.  That is, if cmake --version doesn't run from the
    same terminal window from which you are reading this error message, then
    you have not installed cmake.  Windows users should take note that they
    need to tell the cmake installer to add cmake to their PATH.  Since you
    can't run commands that are not in your PATH.  This is how the PATH works
    on Linux as well, but failing to add cmake to the PATH is a particularly
    common problem on windows and rarely a problem on Linux.

================================================================================
================================================================================
================================================================================
[end of output]

note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed building wheel for dlib
Running setup.py clean for dlib
Building wheel for face-recognition-models (setup.py) … done
Created wheel for face-recognition-models: filename=face_recognition_models-0.3.0-py2.py3-none-any.whl size=100566171 sha256=db67d7aef7c223e406c3a5472c0f00e91709fad989583ccd073d444893f8a198
Stored in directory: /root/.cache/pip/wheels/04/52/ec/9355da79c29f160b038a20c784db2803c2f9fa2c8a462c176a
Successfully built face-recognition-models
Failed to build dlib
ERROR: Could not build wheels for dlib, which is required to install pyproject.toml-based projects


This error happens if you don’t have cmake installed. Unfortunately, installation instructions depend on your operating system. We recommend using a docker-based solution to ease this process. Here’s how you can install it on an Ubuntu machine:

apt update && apt install cmake -y

Error: No CMAKE_CXX_COMPILER could be found

Click to see the full error

Collecting face_recognition
Using cached face_recognition-1.3.0-py2.py3-none-any.whl.metadata (21 kB)
Collecting face-recognition-models>=0.3.0 (from face_recognition)
Using cached face_recognition_models-0.3.0-py2.py3-none-any.whl
Collecting Click>=6.0 (from face_recognition)
Using cached click-8.1.7-py3-none-any.whl.metadata (3.0 kB)
Collecting dlib>=19.7 (from face_recognition)
Using cached dlib-19.24.6.tar.gz (3.4 MB)
Preparing metadata (setup.py) ... done
Collecting numpy (from face_recognition)
Using cached numpy-2.1.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.metadata (62 kB)
Collecting Pillow (from face_recognition)
Using cached pillow-10.4.0-cp311-cp311-manylinux_2_28_aarch64.whl.metadata (9.2 kB)
Using cached face_recognition-1.3.0-py2.py3-none-any.whl (15 kB)
Using cached click-8.1.7-py3-none-any.whl (97 kB)
Using cached numpy-2.1.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (14.0 MB)
Using cached pillow-10.4.0-cp311-cp311-manylinux_2_28_aarch64.whl (4.4 MB)
Building wheels for collected packages: dlib
Building wheel for dlib (setup.py) ... error
error: subprocess-exited-with-error

× python setup.py bdist_wheel did not run successfully.
│ exit code: 1
╰─> [65 lines of output]
running bdist_wheel
running build
running build_ext
Building extension for Python 3.11.10 (main, Sep 12 2024, 23:51:51) [GCC 12.2.0]
Invoking CMake setup: ‘cmake /tmp/pip-install-9spv3qq7/dlib_df80bbb7486545e3a30278bdd2fa278a/tools/python -DCMAKE_LIBRARY_OUTPUT_DIRECTORY=/tmp/pip-install-9spv3qq7/dlib_df80bbb7486545e3a30278bdd2fa278a/build/lib.linux-aarch64-cpython-311 -DPYTHON_EXECUTABLE=/usr/local/bin/python3.11 -DDLIB_USE_FFMPEG=OFF -DCMAKE_BUILD_TYPE=Release’
– The C compiler identification is GNU 12.2.0
– The CXX compiler identification is unknown
– Detecting C compiler ABI info
– Detecting C compiler ABI info - done
– Check for working C compiler: /usr/bin/cc - skipped
– Detecting C compile features
– Detecting C compile features - done
CMake Error at CMakeLists.txt:14 (project):
No CMAKE_CXX_COMPILER could be found.


    Tell CMake where to find the compiler by setting either the environment
    variable "CXX" or the CMake cache entry CMAKE_CXX_COMPILER to the full path
    to the compiler, or to the compiler name if it is in the PATH.


-- Configuring incomplete, errors occurred!
See also "/tmp/pip-install-9spv3qq7/dlib_df80bbb7486545e3a30278bdd2fa278a/build/temp.linux-aarch64-cpython-311/CMakeFiles/CMakeOutput.log".
See also "/tmp/pip-install-9spv3qq7/dlib_df80bbb7486545e3a30278bdd2fa278a/build/temp.linux-aarch64-cpython-311/CMakeFiles/CMakeError.log".
Traceback (most recent call last):
    File "<string>", line 2, in <module>
    File "<pip-setuptools-caller>", line 34, in <module>
    File "/tmp/pip-install-9spv3qq7/dlib_df80bbb7486545e3a30278bdd2fa278a/setup.py", line 243, in <module>
    setup(
    File "/usr/local/lib/python3.11/site-packages/setuptools/__init__.py", line 87, in setup
    return distutils.core.setup(**attrs)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    File "/usr/local/lib/python3.11/site-packages/setuptools/_distutils/core.py", line 185, in setup
    return run_commands(dist)
            ^^^^^^^^^^^^^^^^^^
    File "/usr/local/lib/python3.11/site-packages/setuptools/_distutils/core.py", line 201, in run_commands
    dist.run_commands()
    File "/usr/local/lib/python3.11/site-packages/setuptools/_distutils/dist.py", line 968, in run_commands
    self.run_command(cmd)
    File "/usr/local/lib/python3.11/site-packages/setuptools/dist.py", line 1217, in run_command
    super().run_command(command)
    File "/usr/local/lib/python3.11/site-packages/setuptools/_distutils/dist.py", line 987, in run_command
    cmd_obj.run()
    File "/usr/local/lib/python3.11/site-packages/wheel/_bdist_wheel.py", line 378, in run
    self.run_command("build")
    File "/usr/local/lib/python3.11/site-packages/setuptools/_distutils/cmd.py", line 319, in run_command
    self.distribution.run_command(command)
    File "/usr/local/lib/python3.11/site-packages/setuptools/dist.py", line 1217, in run_command
    super().run_command(command)
    File "/usr/local/lib/python3.11/site-packages/setuptools/_distutils/dist.py", line 987, in run_command
    cmd_obj.run()
    File "/usr/local/lib/python3.11/site-packages/setuptools/_distutils/command/build.py", line 132, in run
    self.run_command(cmd_name)
    File "/usr/local/lib/python3.11/site-packages/setuptools/_distutils/cmd.py", line 319, in run_command
    self.distribution.run_command(command)
    File "/usr/local/lib/python3.11/site-packages/setuptools/dist.py", line 1217, in run_command
    super().run_command(command)
    File "/usr/local/lib/python3.11/site-packages/setuptools/_distutils/dist.py", line 987, in run_command
    cmd_obj.run()
    File "/tmp/pip-install-9spv3qq7/dlib_df80bbb7486545e3a30278bdd2fa278a/setup.py", line 168, in run
    self.build_extension(ext)
    File "/tmp/pip-install-9spv3qq7/dlib_df80bbb7486545e3a30278bdd2fa278a/setup.py", line 206, in build_extension
    subprocess.check_call(cmake_setup, cwd=build_folder)
    File "/usr/local/lib/python3.11/subprocess.py", line 413, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['cmake', '/tmp/pip-install-9spv3qq7/dlib_df80bbb7486545e3a30278bdd2fa278a/tools/python', '-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=/tmp/pip-install-9spv3qq7/dlib_df80bbb7486545e3a30278bdd2fa278a/build/lib.linux-aarch64-cpython-311', '-DPYTHON_EXECUTABLE=/usr/local/bin/python3.11', '-DDLIB_USE_FFMPEG=OFF', '-DCMAKE_BUILD_TYPE=Release']' returned non-zero exit status 1.
[end of output]

note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed building wheel for dlib
Running setup.py clean for dlib
Failed to build dlib
ERROR: Could not build wheels for dlib, which is required to install pyproject.toml-based projects


This error happens when cmake cannot find a suitable compiler. To fix it, you need to install g++. Unfortunately, installation instructions depend on your operating system. We recommend using a docker-based solution to ease this process. Here’s how you can install it on an Ubuntu machine:

apt update && apt install g++ -y

Installation getting stuck

The installation will take some time. As a reference, in my laptop, it took 7 minutes. You’ll notice that during the installation, a message like this will appear:

Building wheel for dlib (setup.py) ... /

Just wait for it to finish, you’ll see something like this once the process finishes:

Successfully built dlib
Installing collected packages: face-recognition-models, dlib, Pillow, numpy, Click, face_recognition
Successfully installed Click-8.1.7 Pillow-10.4.0 dlib-19.24.6 face-recognition-models-0.3.0 face_recognition-1.3.0 numpy-2.1.1

Streamlit app not loading

You might also experience issues when starting Streamlit. If you start the app and it never finishes loading, there might be an installation issue. To troubleshoot, try impporting face_recognition and face_recognition_models:

python -c 'import face_recognition'

Important: import face_recognition might throw the following error:

Please install `face_recognition_models` with this command before using `face_recognition`:

pip install git+https://github.com/ageitgey/face_recognition_models

However, such error is misleading. The actual error might not be that you’re missing face_recognition_models. To know for sure, run the following:

python -c 'import face_recognition_models'

If you see the following error:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'face_recognition_models'

Then, you need to install face_recognition_models:

pip install git+https://github.com/ageitgey/face_recognition_models

However, you might see a different error:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/usr/local/lib/python3.12/site-packages/face_recognition_models/__init__.py", line 7, in <module>
    from pkg_resources import resource_filename
ModuleNotFoundError: No module named 'pkg_resources'

This happens because face_recognition_models is not compatible with newer versions of Python, the solution is to use Python 3.11.

If both import face_recognition and import face_recognition_models, you’re good to go!

Deployment

Unfortunately, according to a Streamlit team member, face_recognition cannot be deployed to Streamlit Community Cloud:

streamlit-cloud

Here we’ll show you how to deploy it to Ploomber Cloud. The source code is available on GitHub.

Here are the instructions:

# install ploomber cloud cli
pip install ploomber-cloud

# download example
ploomber-cloud examples streamlit/streamlit-face-recognition
cd streamlit-face-recognition

Note that you’ll need a Ploomber Cloud account to continue:

# initialize the project
ploomber-cloud init

# deploy
ploomber-cloud deploy

After a few minutes, you’ll have the application up and running!