🌐 Company Site - Here
🤗 Hugging Face - Here
🛟 Help Center - Here
🐳 Docker Hub - Here
Ready in minutes:
docker pull→ copyFPMC1.…from logs →curl /api/health.
Jump: Quick Start · Start the API · SDK License · Setup on your own app · Try it
- Download and run the appropriate Docker image from FacePlugin Docker Hub. See Option A for details.
- Confirm it is running:
curl -s http://127.0.0.1:8083/api/health(no license needed yet) - Contact us with your machine code (
FPMC1.…) to obtain a license key, then activate withPOST /api/activate— SDK License - Try it: Postman, curl, or local Gradio demo on 9003 (
demo.py)
Docs: https://doc.faceplugin.com
FacePlugin Face Recognition SDK for Linux / Docker is a fully on-premise biometric engine for KYC, access control, and identity verification. It runs face detection (bounding box, landmarks, pose, attributes), ICAO-style face quality, template extraction, 1:1 matching, and feature similarity — all on your server.
This repository is standalone. Pull Docker Hub (no Drive) or download the runtime into this repo and run — no other FacePlugin repository is required.
All processing stays on your server. No biometric data is sent to FacePlugin cloud — built for banking, eKYC, and on-premise compliance workflows.
One repository for Linux SDK + Docker. Native libraries are linux/amd64; the Docker image runs on Linux, Windows, and macOS hosts via Docker (Apple Silicon uses amd64 emulation). This product is CPU-only.
Test with Postman, curl, or the local Gradio demo (demo.py) covering Detect, Quality, and Match. Docs: https://doc.faceplugin.com.
| Feature | API |
|---|---|
| Face detection (bounding box, landmarks, pose, attributes) | POST /api/detect · sdk.detect |
| Face quality analysis (ICAO-style checks) | POST /api/quality · sdk.quality |
| Face template extraction for matching | POST /api/feature · sdk.feature |
| 1:1 face match (two images) | POST /api/match · sdk.match |
| Feature vector similarity scoring | POST /api/similarity · sdk.similarity |
| Health / machine code / activate | GET /api/health · GET /api/machinecode · POST /api/activate |
| Platform | Repository |
|---|---|
| Android (Recognition) | FaceRecognition-Android |
| iOS (Recognition) | FaceRecognition-iOS |
| React Native (Recognition) | FaceRecognition-React-Native |
| Flutter (Recognition) | FaceRecognition-Flutter |
| Ionic Capacitor (Recognition) | FaceRecognition-Ionic-Capacitor |
| Ionic Cordova (Recognition) | FaceRecognition-Ionic-Cordova |
| Windows (Recognition) | FaceRecognition-Windows |
| Linux / Docker (Recognition) | FaceRecognition-Docker (this repo) |
| Android (Liveness) | FaceLivenessDetection-Android |
| iOS (Liveness) | FaceLivenessDetection-iOS |
| Windows (Liveness) | FaceLivenessDetection-Windows |
| Linux / Docker (Liveness) | FaceLivenessDetection-Docker |
| Step | What you need |
|---|---|
| 1 | A Linux host or Docker (Desktop or Engine) |
| 2 | Docker Hub pull does not need Drive. Fill ./lib/cpu/ only for Compose / ./run.sh — see Get the runtime |
| 3 | Start without a license. Copy FPMC1.… from logs or GET /api/machinecode, send it to FacePlugin (contact), then activate with your license key |
You do not need a license to start the API once. Product endpoints unlock after you activate.
| Item | Minimum | Recommended |
|---|---|---|
| CPU | 2 cores | 8 cores |
| RAM | 4 GB | 8 GB |
| Disk | 4 GB | 8 GB |
| OS (Docker) | Linux + Docker Engine | Ubuntu 22.04 / 24.04 |
OS (local ./run.sh) |
glibc 2.38+ (e.g. Ubuntu 24.04), Python 3.10+ | Ubuntu 24.04, Python 3.12 |
You can start without a license — the server prints your machine code on startup.
The API starts even if activation fails. Copy the machine code (FPMC1.…) from the log and send it to FacePlugin.
Runtime is already inside the image.
sudo docker pull faceplugin/face-recognition:latest
sudo docker run -d --name faceplugin-face-recognition \
--shm-size=2gb --privileged \
-p 8083:8083 \
-v /etc/machine-id:/etc/machine-id:ro \
faceplugin/face-recognition:latest
sudo docker logs -f faceplugin-face-recognition
# Look for the machine code line: FPMC1.…You only need this section if you want to run multiple Face Recognition containers on the same Linux host.
On Linux, mount /etc/machine-id into each container so they use the same machine code. Each container must have a different container name and host port.
For example:
sudo docker run -d --name faceplugin-face-recognition-2 \
--shm-size=2gb --privileged \
-p 8084:8083 \
-v /etc/machine-id:/etc/machine-id:ro \
faceplugin/face-recognition:latestYou can then activate each container using the same FP1.… license key.
Note: On Docker Desktop (macOS/Windows), do not use the /etc/machine-id volume. Each container may require its own license.
Skip this if you used Docker Hub (docker pull / docker run). Runtime is already inside the image.
./lib/cpu/ is empty on GitHub because native binaries and models are too large. Face Recognition Linux is CPU-only — there is no gpu/ package.
FaceRecognition-Docker runtime (Google Drive)
- Clone the repo (if you have not already):
git clone https://github.com/Faceplugin-ltd/FaceRecognition-Docker.git
cd FaceRecognition-Docker- Open the Google Drive folder. Download all files (select all → Download, or zip).
- Put every file directly into
./lib/cpu/— not inside a nested subfolder.
FaceRecognition-Docker/
└── lib/
└── cpu/
├── libFaceRecognitionSDK.so
├── libfar-eng.so
├── far.fpk
└── ... (runtimes from Drive)
Wrong layout: lib/cpu/SomeFolder/libFaceRecognitionSDK.so (a nested folder breaks Docker build and local runs).
ls lib/cpu/libFaceRecognitionSDK.so
ls lib/cpu/libfar-eng.soIf those paths exist, you are ready for Option B or C.
Requires ./lib/cpu/ filled from Drive.
cd FaceRecognition-Docker
# macOS/Windows Docker Desktop: remove the /etc/machine-id volume from docker-compose.yml first
sudo docker compose up --build -d
sudo docker compose logs -f
# Look for the machine code line: FPMC1.…
# Detached Compose has no TTY — there is no license prompt. Activate with curl (below).Requires ./lib/cpu/ filled from Drive.
cd FaceRecognition-Docker
pip3 install -r requirements.txt
./run.sh
# or: python3 app.py
# The machine code (FPMC1.…) is printed in the terminal on startup.Licenses are offline and bound to your machine code. Offline cryptography is built into the SDK — no OpenSSL install.
- Start the server (above) — Docker or local. A license is not required for the first start.
- Copy the machine code from the startup log (container logs or the local terminal). It looks like
FPMC1.…. - Send that machine code to FacePlugin (contact). We will issue a license key for that code.
- Activate with the license key:
# Paste your license key into ./license.txt (overwrite the file).
# Docker Hub (A) and Compose (B) both expose the API on this host port.
# `docker compose up -d` does not activate — the container is already running
# with no TTY, so it will not re-read license.txt. POST the key instead:
curl -s -X POST http://127.0.0.1:8083/api/activate \
-H 'Content-Type: text/plain' \
--data-binary @license.txt
# Compose alternative: after writing license.txt, restart so startup activates:
# sudo docker compose restart
# Local (Option C): stop the process (Ctrl+C), then:
./run.sh
Use the machine code from the environment you will run in production. Docker and local host codes are different — if you run in Docker, send the Docker machine code.
curl -s http://127.0.0.1:8083/api/healthImport postman/FaceRecognition-API.postman_collection.json.
Default base URL: http://127.0.0.1:8083
Routes are /api/* (no version segment in paths).
The Docker image is API/SDK server only (no Gradio). For a local FacePlugin Face Recognition demo in the browser — Detect, Quality, and Match — on the host (API must already be running on port 8083):
pip3 install -r requirements-demo.txt
DEMO_PORT=9003 API_BASE=http://127.0.0.1:8083 python3 demo.pyOpen http://127.0.0.1:9003. Examples when present: assets/examples/samples/.
Tabs: Detect, Quality, Match. Each action has a Result table (attributes, quality checks, or match scores) and Raw JSON for integration. Detect / Quality examples are every file under assets/examples/samples/. Match is Odd vs Even: pick one image from each group, then Match.
Two ways to call the same engine. Full protocol: https://doc.faceplugin.com.
| Path | When to use |
|---|---|
HTTP (app.py) |
Any language. Keep this API running and POST images as JSON. |
sdk.py |
Python on the same Linux host as lib/cpu/ (or inside the container). No HTTP hop. |
HTTP (any language): start the API, then call /api/detect, /api/quality, /api/match, /api/feature, /api/similarity. Images are base64. See Try it and Postman.
Python in-process: copy sdk.py + lib/cpu/ into your project (or import sdk from this repo). Call order: get_machine_code → activate → init_sdk → detect / quality / feature / match / similarity. Return code 0 means success.
You do not need Gradio (demo.py) in production — it is a host-only test UI.
Use the Python bindings in sdk.py. Return code 0 means success.
First, obtain the machine code for activation and request a license based on the machine code.
import sdk
machine_code = sdk.get_machine_code()
print("machineCode:", machine_code) # FPMC1.…Next, activate the SDK with the path to your license file (license.txt containing your license key).
ret = sdk.activate("license.txt")If activation is successful, the return value will be 0. Otherwise, an error value will be returned.
After activation, call the initialization function of the SDK.
ret = sdk.init_sdk()If initialization is successful, the return value will be 0. Otherwise, an error value will be returned.
result = sdk.detect(base64_image, crop_image=False)result = sdk.quality(base64_image, crop_image=False)result = sdk.feature(base64_image)result = sdk.match(base64_image1, base64_image2, crop_image=False)result = sdk.similarity(feature1_b64, feature2_b64)
