Quick Start

Quick Start

Running both halves locally from source. If you only want to use the app, the prebuilt executable is far less work.

Prerequisites

• Python 3.10 or newer (3.12 is what the project is developed against)
• Node.js 18 or newer, and npm
• A C++ toolchain, only if you install dlib from source — see Installing dlib below

1. Clone

git clone https://github.com/mrbeandev/Face-Gallery.git
cd Face-Gallery

2. Backend

cd face-detection-webapp/backend

python3 -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows

pip install -r requirements.txt
python -m uvicorn main:app --port 8000

The API is now on http://localhost:8000. Check it with:

curl http://localhost:8000/health

In development the backend stores uploads, results, thumbnails, and the SQLite database in the directory you ran it from.

The default --host is loopback, which is what you want. Do not bind 0.0.0.0 unless you intend to publish an unauthenticated photo backend to your whole network.

3. Frontend

In a second terminal:

cd face-detection-webapp/frontend
npm install
npm run dev

The app is now on http://localhost:5173. The Vite dev server proxies /api, /ws, /thumb, and /static to the backend, so no CORS setup is needed for local development.

4. Connect

Open http://localhost:5173. On first launch you are asked for the backend URL, prefilled with http://localhost:8000. Click Test & Connect.

You can skip the dialog entirely with http://localhost:5173/?backend=http://localhost:8000.

Installing dlib

face_recognition depends on dlib, which is compiled C++. Installing it from source needs CMake and a compiler:

Ubuntu / Debian

sudo apt update
sudo apt install -y cmake build-essential libopenblas-dev liblapack-dev libx11-dev

macOS

brew install cmake

Windows

Install CMake and the Visual Studio Build Tools with the "Desktop development with C++" workload.

Skipping the compile

A source build takes a long time and needs a fair amount of memory. The dlib-bin package ships prebuilt wheels for Linux x86_64 and aarch64, Windows x64, and Apple Silicon, and provides the same dlib module:

pip install dlib-bin
pip install --no-deps face_recognition face_recognition_models
pip install -r requirements.txt

This is what the release workflow does. See Building the Executable.

If the import fails

ModuleNotFoundError: No module named 'pkg_resources' means setuptools is missing. Python 3.12 virtual environments no longer include it, and setuptools 81 removed pkg_resources, which face_recognition_models needs:

pip install "setuptools<81"

requirements.txt already pins this. More in Troubleshooting.