Faceplugin Open Source Face Recognition SDK: On-Premise Python Face Matching, and What the README Leaves Out

The gap this repository fills, and the gap it deliberately leaves open

Most face recognition code you can install from a package index either ships as a research model with no stable API, or as a cloud endpoint that bills per call and receives your images. Faceplugin positions this SDK against both. The README's own phrase is "100% On-Premise", and the feature list repeats the privacy point: no data leaves the device. For a team handling employee photos, access-control enrolment images or any dataset covered by a data protection regime, that constraint is the reason to look at the project at all.

The audience is narrower than the topic list suggests. The README targets Windows and Linux with Python 3.9 or higher, and recommends Anaconda for dependency management. There is no Docker image in this repository, no mobile binding, and no service wrapper. If you wanted a face recognition microservice, you would be writing that layer yourself around the Python calls.

The capability boundary is explicit in the README's own marketing table. Face liveness detection, ID document recognition and ID document liveness detection appear as separate commercial SDKs from the same vendor. The open source repository covers detection, landmarks, embeddings and comparison. That is a matching library, not an identity verification system, and the distinction matters when you decide where in your stack it belongs.

Inside the pipeline: detection, landmarks, embedding, cosine-style comparison

The public surface is two methods. GetImageInfo(image_path, faceMaxCount) reads an image from disk and returns a list of dictionaries, one per detected face, each carrying a bbox, a set of landmarks, and an embedding vector. get_similarity(feature1, feature2) takes two of those embeddings and returns a score between 0 and 100, where higher means more alike. The README's example treats 75 as the cut-off for "same person".

That is the whole data flow as documented. An image goes in, a bounding box localises each face, landmarks give the alignment points, and the embedding is the numeric representation that survives comparison. The README does not describe the model architecture, the embedding dimensionality, or whether the similarity is cosine distance rescaled to a percentage. All three matter in production. Embedding size determines your storage per enrolled person; the metric determines whether 75 is a sensible threshold for your population or an arbitrary number copied from a demo.

The multi-face behaviour is worth noting for integration design. faceMaxCount caps how many faces are returned, so a group photo passed with faceMaxCount=1 gives you whichever face the detector ranked first. The README does not state the ranking rule. If your application assumes the largest or most central face, verify that assumption against real images rather than trusting the parameter name.

Supported input formats are listed as JPG, PNG, BMP and TIFF. That is a still-image interface. There is no webcam or video stream API in the documentation, so a real-time attendance terminal would mean reading frames yourself and calling GetImageInfo per frame, paying the per-call detection cost each time.

Getting it running: conda, requirements.txt, run.py

The install path in the README is short and conventional. Create a Python 3.9 environment, install the pinned dependencies, then run the bundled script:

conda create -n facesdk python=3.9 conda activate facesdk pip install -r requirements.txt python run.py

The README describes python run.py as the installation test, which suggests the repository ships a runnable entry point rather than only a library. It does not document what run.py prints, what arguments it accepts, or which images it expects. Treat it as a smoke test and read the file before executing it on a machine with sensitive data on disk.

Usage after install is a class import and two calls. The README shows from face_recognition_sdk import FaceRecognition, then face_sdk = FaceRecognition(), then face_sdk.GetImageInfo(image_path, faceMaxCount=10). The naming is inconsistent: GetImageInfo is PascalCase while get_similarity is lower case, which is a small friction in an otherwise tidy API.

The configuration surface documented is thin. The only tunable mentioned is the default threshold of 75, and it is described in prose rather than as a named configuration key. There is no documented config file, no environment variable, and no model path setting. If the models are bundled or downloaded on first run, the README does not say which. That is the first thing to check in the repository tree, because it determines whether your deployment needs network access at install time.

Why the missing liveness detection is the load-bearing limitation

A face matcher answers one question: are these two embeddings close enough. It does not answer whether the face in front of the camera is a live person. The README's own product table places Face Liveness Detection in the commercial column, which is an honest signal that the open source tier does not include presentation attack defence.

For a photo-album organiser or an internal tool that deduplicates employee headshots, that absence is irrelevant. For access control, biometric login or attendance, it is the difference between a working system and one that a printed photograph defeats. The README's use case section lists access control, user authentication and surveillance, which invites exactly the deployment the open source tier cannot secure on its own. Read that section as a description of the market, not as a statement of what the shipped code does.

Other limits are visible in the documentation itself. The platform badge covers Windows and Linux, so macOS and ARM-based single-board computers are unverified. There are no retrieved releases, which means there is no changelog to consult for breaking changes. The README also does not report accuracy figures on any named benchmark, so the phrase "high accuracy" in the feature list is a claim without a number attached. You would need your own evaluation set before trusting the 75 threshold on real faces, particularly across age, lighting and camera differences between enrolment and probe images.

Alternatives: what you give up when you leave the model behind the API

The obvious comparison is InsightFace, the widely used Python face analysis library built on ONNX Runtime. The architectural difference is where the model lives. InsightFace exposes model packs and lets you choose the detection and recognition networks, swap them, and inspect the embedding space directly. Faceplugin's SDK hides that choice behind GetImageInfo and get_similarity, which is easier to start with and harder to tune when a particular camera angle or demographic group underperforms.

A second comparison is a cloud face API from a major provider. Those bundle liveness and document checks into the same endpoint, which removes the integration work Faceplugin leaves to you, at the cost of sending face images to a third party. The README's on-premise claim is precisely the counter-argument, and for regulated data it is a strong one.

The honest framing is that this SDK trades control for simplicity. If you need to swap the recognition model, quantise it for an edge device, or reproduce a published benchmark, the abstraction is in your way. If you need embeddings and a similarity score from a Python process on a Windows workstation, the two-method API is proportionate to the task.

Licence, maintenance and the cost of staying current

The repository metadata supplied here lists the licence as unknown, and the README's badge reads "Open Source" with a link back to the repository rather than to a named licence text. That is not the same as a permissive licence. "Completely free" and "no licensing fees" appear in the feature list, but those are marketing statements, not grant terms. Commercial use, redistribution inside a product, and patent questions all depend on the actual licence file, which you should locate in the repository before adopting anything. This is a description of the gap, not legal advice; if the terms are unclear, that is a question for counsel.

Maintenance signals are mixed. The default branch is main, the repository is not archived, and the last push date is recent, so the project is active. There are no retrieved releases, which means versioning may be commit-based rather than tag-based. Pinning to a commit hash is the safer integration choice, because a git pull could change behaviour under you with no changelog to warn you.

The upgrade cost concentrates in two places: the model weights and the threshold. If a future model changes the embedding space, your stored embeddings from previous enrolments may no longer be comparable, forcing a re-enrolment pass. The README does not state an embedding version or compatibility guarantee. Budget for a re-enrolment path, and store the model identifier alongside each embedding so you can tell which generation a template came from.

Where this SDK belongs in a real system

The sensible deployment is as a matching component inside a pipeline you already control. Enrolment produces an embedding per person and stores it next to an identifier. Verification calls GetImageInfo on a probe image, takes the first face, and calls get_similarity against the stored template. Everything around that, including liveness, document checks, threshold tuning per camera, and audit logging, is your responsibility.

The threshold deserves explicit treatment rather than a hardcoded 75. The README's example uses 75 for a same-person decision, but a single global number cannot serve both a low-security photo deduplication task and a door-opening decision. Collect genuine and impostor pairs from your own cameras, then pick the operating point from that data. The SDK returns a score, so this is a calibration exercise on your side, not a configuration change in the library.

One integration detail worth deciding early: whether to persist the landmarks and bounding boxes or only the embedding. The README returns all three from GetImageInfo. Storing the full record costs more space but lets you re-align or debug a rejected match later without re-running detection on the original image, which may no longer be available if your retention policy deletes source photos.

Editorial conclusion

Adopt this SDK if you need a small, self-contained Python component that turns images into embeddings and compares them on hardware you control, and if you can accept that the repository does not state a licence. Do not adopt it as the verification layer for a security decision, because the README lists no liveness or anti-spoofing capability here; those are separate commercial products in the same vendor's catalogue. Before writing any code, confirm three things: the licence file or terms attached to the repository, the exact contents of requirements.txt and the model weights it pulls, and whether get_similarity's 0 to 100 score is calibrated the same way across the image formats you plan to accept.

Official sources

1. Faceplugin-ltd/Open-Source-Face-Recognition-SDK on GitHub
2. Issues
3. Project website
4. README