CompreFace

Last reviewed Aug 26, 2026 · 869 words

Budget 4 GB of RAM for CompreFace before you decide anything else. The catalogue's 4,096 MB minimum is honest: the face-recognition core loads a neural network into memory on start, and on a 2 GB host it either fails to come up or thrashes into uselessness. On a box with 8 GB and a few CPU cores it recognises a face from a still image in well under a second, exposes it as a plain REST call, and asks nothing of you in machine-learning knowledge. That trade, memory for simplicity, is the whole product.

The five containers and what each one costs

CompreFace ships as a Docker compose file downloaded from its GitHub releases, and it always brings five services: a Postgres database, an admin service, an API service, a core service that does the actual detection and recognition, and an nginx front end serving the web UI and proxying the API on port 8000. The core service is the memory hog; the Java admin and API services take a few hundred megabytes each; Postgres is small. Nothing here is optional, but the compose is self-contained enough that a first run is genuinely docker compose up -d followed by opening http://host:8000.

The releases page offers several builds of the same version. The default CPU build uses the full model. The "mobilenet" build swaps in a lighter model that runs on about half the memory and is noticeably faster on weak CPUs, at a cost in accuracy that for a home setup with 5 to 10 known faces is hard to notice. A GPU build exists for NVIDIA cards. Pick mobilenet on anything with less than 8 GB and move up only if you see misidentifications.

Applications, services and API keys are the model

Open the UI, create a user, then create an application. Inside it, create a service of one of three types: recognition (who is this), verification (is this the same person as that), or detection (where are the faces, plus age, gender and landmarks if you ask). Each service gets its own API key, and that key is the only auth on the REST API. Add a subject by uploading example photos, then send an image and read the answer:

curl -X POST "http://host:8000/api/v1/recognition/recognize" \
  -H "x-api-key: YOUR_SERVICE_KEY" \
  -F "[email protected]"

The response is a list of faces with the best-matching subject names and a similarity score between 0 and 1. Three or four clear photos per person from different angles gets a household to reliable matches; 10 or more from real camera frames, not portraits, gets it to reliable matches at 3 metres in bad light. Train from your actual cameras, not from phone selfies.

It is a recognition service, not a surveillance system

CompreFace does not watch cameras, record video, or send you alerts. It answers questions about images you send it. That is the "recognition service only" con and it is a design decision: the system that owns the cameras is Frigate, which detects people and objects, and the bridge is Double Take, which subscribes to Frigate's person events over MQTT, sends the crops to CompreFace, and publishes the name back to MQTT. From there Home Assistant can release a door lock, silence a "person detected" notification for family, or announce a stranger. That three-piece stack is the standard homelab pattern and the reason CompreFace is filed under video surveillance.

Expect Double Take to send several crops per event, so the recognition service will see bursts of 5 to 20 requests in a second or two. On a 4-core CPU with the mobilenet build that is fine; on a Raspberry Pi it is not, and I would not run CompreFace on a Pi at all.

Keep it inside the network and keep the database

The API key is a single static secret and the UI has no rate limiting or second factor, so CompreFace should never be reachable from the internet. Bind port 8000 to a LAN or VPN address and let Double Take and Home Assistant talk to it locally. Back up the Postgres volume; it holds the subjects, the face embeddings and the application keys, and losing it means re-enrolling everyone. Photos you uploaded are stored as embeddings plus optional originals, and deleting a subject removes both, which matters if a house guest asks you to.

What I'd do

Run the mobilenet CPU build on a box with at least 8 GB total, bound to a LAN address, with Frigate and Double Take alongside it. Enrol each household member with 10 or so frames captured from the doorbell camera, set Double Take's confidence threshold high enough that "unknown" is the honest default, and let Home Assistant act on names rather than on raw person detections. Back up Postgres weekly. If you only want to know whether a person is at the door, Frigate alone answers that; CompreFace is for when you want to know which person, and it does that well for the cost of 4 GB.