Facial recognition on your own hardware, with your own rules, and zero data shared with a third party – that is what Immich delivers. The open-source photo management platform has quietly built one of the most capable self-hosted alternatives to Google Photos, and its machine-learning facial recognition feature is the piece that keeps privacy-conscious users coming back.
What Immich Actually Does With Your Faces
Immich uses a local machine learning server – bundled as a separate Docker container – to run face detection and recognition entirely on your machine. When you upload a photo, Immich’s ML service scans for faces, generates a numerical embedding (a mathematical representation of each face), and stores that data in its PostgreSQL database. No image or embedding ever leaves your server. The recognition model it ships with is based on InsightFace, a well-regarded open-source framework used in academic and commercial computer vision work.
The system clusters similar face embeddings together and presents them in the “People” section of the web UI. From there, you assign names to each cluster, and Immich uses those labeled embeddings to improve future matches. The more photos you feed it over time, the more accurate the groupings become – especially for faces photographed across different lighting conditions, ages, and angles. It is not magic; it is cosine similarity math running locally on your CPU or GPU.
One thing worth understanding before setup: Immich separates face detection from face recognition. Detection finds faces in images. Recognition links those detected faces to known people. Both are handled by the immich-machine-learning container, but they run as distinct processes. This matters because you can tune each independently – for example, lowering the recognition threshold if the system is splitting one person into multiple clusters, or raising the detection sensitivity if it is missing faces in crowded group shots.
Immich also supports hardware acceleration for the ML workload. If your server has an NVIDIA GPU, you can configure the machine learning container to use CUDA, which dramatically cuts the time it takes to process large libraries. For most home server setups running on a modest CPU, expect processing to take several hours for a library of tens of thousands of photos – perfectly acceptable for a background task, but worth scheduling during off-peak hours.
Setting Up Immich With Facial Recognition Enabled
The standard Immich deployment uses Docker Compose, and the official documentation provides a docker-compose.yml file that includes the machine learning container by default. Start by downloading that file along with the accompanying .env file from the Immich GitHub releases page. Open the .env file and set your UPLOAD_LOCATION to a directory with enough storage for your photo library, then set DB_PASSWORD to a strong password of your choosing.
The docker-compose.yml includes the immich-machine-learning service out of the box. By default it mounts a model cache volume so that downloaded models persist across container restarts – you do not want it re-downloading several hundred megabytes of model weights every time you update. Confirm that the service definition includes the model-cache volume mount before running the stack. Once your files are configured, bring everything up with docker compose up -d and let Docker pull the images.
After the containers are running, navigate to your server’s IP on port 2283 to complete the initial setup wizard. Create your admin account, then go to Administration – Machine Learning Settings. This panel controls the face detection and recognition parameters directly. The key settings to pay attention to are “Minimum Detection Score” (how confident the model must be before marking something as a face) and “Maximum Recognition Distance” (how different two face embeddings can be before Immich treats them as different people). The defaults work well for most libraries, but expect to revisit these after your first full scan.
To trigger the initial facial recognition job, go to Administration – Jobs and run “Generate Embeddings” followed by “Perform Facial Recognition.” These are separate jobs and must be run in that order. The embedding job processes every photo and extracts face data; the recognition job then clusters and links those embeddings to people profiles. On a large library, these jobs can run for a long time. The Jobs panel shows live progress, and you can monitor the immich-machine-learning container logs with docker logs -f immich_machine-learning if you want to watch processing in real time.
Once the jobs complete, open the Explore tab and select People. Immich will show face clusters – some accurate, some needing correction. Click on a cluster, assign a name, and then use the “Add more photos” option to manually pull in any faces the system missed or split incorrectly. Every correction feeds back into the recognition model’s understanding of that person. If you find that one person is being split across three or four separate clusters, try lowering the “Maximum Recognition Distance” value slightly and re-running the facial recognition job – it tells the system to be more permissive about grouping similar faces together.
Keeping the System Running and Accurate Over Time
Immich’s facial recognition is not a one-time operation. Every new upload triggers embedding generation automatically if the relevant background tasks are enabled under Administration – Jobs – Job Settings. Toggle on “Generate Embeddings on Upload” and “Perform Facial Recognition on New Faces” so that incoming photos are processed without manual intervention. This is the configuration that makes the system behave like a cloud photo service – new photos analyzed, new faces surfaced, existing people matched – except entirely on your own hardware.
Model updates are worth watching for in Immich release notes. The project periodically upgrades the bundled InsightFace weights, and switching to a newer model version requires re-running the full embedding and recognition pipeline on your entire library – a significant but worthwhile task when accuracy improvements are meaningful. If you are also running other self-hosted services that depend on organized personal data, Immich fits naturally alongside something like a self-hosted file storage server, giving you a complete local alternative to cloud-dependent photo and file management. The real long-term maintenance question for Immich is whether your server hardware keeps pace with a growing library – face recognition accuracy does not degrade, but processing time per new upload increases as the people database grows and more comparisons must be made per face.
