Face Recognition SDK — Linux / Docker (Fully On-Premise)

🌐 Company Site - Here

🤗 Hugging Face - Here

🛟 Help Center - Here

🐳 Docker Hub - Here

Face Recognition SDK — Linux / Docker (Fully On-Premise)

⚠️GPU version will be delivered soon.

Introduction

Explore FacePlugin Face Recognition SDK — face detection, quality, template extraction, 1:1 verification and 1:N identification.

This is an on-premise FacePlugin SDK. All processing stays on your server — no biometric data is sent to FacePlugin cloud.

One repository for Linux SDK + Docker. The native libraries are linux/amd64; the Docker image runs on Linux, Windows, and macOS hosts via Docker (Apple Silicon uses amd64 emulation).

API server in Docker — test with Postman, curl, or the local Gradio demo (demo.py).

◾ Main Functionalities

Feature	Supported
Face detection	✓
Landmarks / pose / attributes	✓
Template extraction	✓
1:1 verification	✓
1:N identification	✓
Face quality (ICAO)	✓

◾ Product List

Platform	Repository
Android	`FaceRecognition-Android`
iOS	`FaceRecognition-iOS`
Windows	`FaceRecognition-Windows`
Linux / Docker	`FaceRecognition-Linux`
Flutter	`FaceRecognition-Flutter`
React Native	`FaceRecognition-ReactNative`
Python	`FaceRecognition-Python`
C#	`FaceRecognition-CSharp`

FaceRecognition-Linux is one repository: Linux SDK runtime + Docker image (same tree).

Before you start

Step	What you need
1	A Linux host or Docker (Desktop or Engine)
2	Runtime libraries in `./lib/` only if you clone this repo and build/run from it — see Download runtime libraries
3	A license after first start: copy the machine code from the server log, send it to FacePlugin, then activate with the `FP1.…` key

You do not need a license to start the API once. Product endpoints unlock after you activate.

System requirements

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)	Ubuntu 24.04
GPU (optional)	NVIDIA driver + Container Toolkit	CUDA 12 GPU package in `./lib/`

Download runtime libraries (lib folder)

The ./lib/ directory is intentionally left empty because native binaries and model files are too large for GitHub.

If you are building or running directly from this repository, you must download these files separately.

You don't need to manually download the binary files if you pull the official Docker image from Docker Hub—everything is already packaged inside the container. CPU and GPU are different tags on the same Hub repo (faceplugin/face-recognition).

Where to download

CPU (default):
FaceRecognition-Linux runtime (Google Drive)

GPU (optional):
FaceRecognition-Linux GPU runtime (Google Drive)

The GPU Drive folder is not the same as the CPU folder. It must include CUDA 12 + cuDNN .so files next to libFaceSDK.so, and a larger Ort.fpk (CUDA ORT providers inside). The Docker image is still based on slim Python — NVIDIA toolkit mounts the driver only; CUDA userland comes from ./lib/.

Download one variant into ./lib/ (do not mix CPU and GPU files). Start that variant with Option B or Option C.

/api/backend may report "backend":"gpu" from the compose environment; that label alone does not enable CUDA. If check_lib.sh --gpu fails, inference will stay broken or CPU-only.

How to Download Dependencies into `./lib/`

Clone the repo (if you have not already):

git clone https://github.com/Faceplugin-ltd/FaceRecognition-Linux.git
cd FaceRecognition-Linux

Open the matching Google Drive folder from Where to download (CPU or GPU — one variant only, do not mix).
Download all files in that folder (Drive: select all → Download, or download as a zip).
Put every file directly into ./lib/ — not inside a nested subfolder.

Correct layout:

FaceRecognition-Linux/
└── lib/
    ├── libFaceSDK.so
    ├── runtime_payload.json
    └── ... (models, .fpk, and other files from Drive)

Wrong layout: lib/SomeFolder/libFaceSDK.so (a nested folder breaks Docker build and local runs).

Quick check:

ls lib/libFaceSDK.so
ls lib/runtime_payload.json

If those paths exist, you are ready to start.

Start the API

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.

Option A — Docker Hub (no Drive download)

CPU and GPU publish to the same Hub repository with different tags (not two Hub repos):

Variant	Tags (examples)
CPU	`latest-cpu`, `1.0.0-cpu` (`latest` also tracks CPU)
GPU	`latest-gpu`, `1.0.0-gpu`

CPU:

sudo docker pull faceplugin/face-recognition:latest-cpu
# or: sudo docker pull faceplugin/face-recognition:latest
sudo docker run -d --name faceplugin-face-recognition -p 8083:8080 \
  faceplugin/face-recognition:latest-cpu
sudo docker logs -f faceplugin-face-recognition
# Look for the machine code line: FPMC1.…

GPU (NVIDIA driver + Container Toolkit on the host):

sudo docker pull faceplugin/face-recognition:latest-gpu
sudo docker run -d --name faceplugin-face-recognition-gpu -p 8083:8080 \
  --gpus all \
  -e FACEPLUGIN_BACKEND=gpu \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
  faceplugin/face-recognition:latest-gpu
sudo docker logs -f faceplugin-face-recognition-gpu
# Look for the machine code line: FPMC1.…

Do not use a CPU tag with --gpus and expect CUDA — the GPU runtime must be the *-gpu image.

Option B — Building locally with Docker Compose

Requires ./lib/ filled from Drive. Use the CPU Drive folder for CPU, the GPU Drive folder for GPU.

CPU:

cd FaceRecognition-Linux
# 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).

GPU (NVIDIA driver + Container Toolkit on the host; GPU Drive files in ./lib/):

cd FaceRecognition-Linux
./scripts/check_lib.sh --gpu
# GPU Compose needs NVIDIA on Linux. Docker Desktop (macOS/Windows) is not a GPU path.
sudo docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build -d
sudo docker compose -f docker-compose.yml -f docker-compose.gpu.yml logs -f
# Look for the machine code line: FPMC1.…
# Detached Compose has no TTY — there is no license prompt. Activate with curl (below).

Do not run sudo docker compose up --build -d with a GPU ./lib/ and expect CUDA. You must pass docker-compose.gpu.yml.

Option C — Native Linux setup (No Docker)

Requires ./lib/ filled from Drive.

CPU:

cd FaceRecognition-Linux
./run.sh
# or: python3 app.py
# The machine code (FPMC1.…) is printed in the terminal on startup.

GPU (NVIDIA driver on the host; GPU Drive files in ./lib/. Container Toolkit is not required for a native run):

cd FaceRecognition-Linux
./scripts/check_lib.sh --gpu
FACEPLUGIN_BACKEND=gpu ./run.sh
# or: FACEPLUGIN_BACKEND=gpu python3 app.py
# The machine code (FPMC1.…) is printed in the terminal on startup.

FACEPLUGIN_BACKEND=gpu only validates that ./lib/ is a GPU package. CUDA still comes from those files plus the host NVIDIA driver.

SDK License

Licenses are offline and bound to a machine code. Offline cryptography is pre-packaged within the SDK—no third-party licensing libraries or external OpenSSL installations are required.

How to get a license

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 an FP1.… license for that code.
Activate with the FP1.… key:

# Paste the FP1. 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
# GPU Compose: sudo docker compose -f docker-compose.yml -f docker-compose.gpu.yml 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.

Please contact us

Try it

Health

curl -s http://127.0.0.1:8083/api/health

Documentation

https://doc.faceplugin.com

Postman

Import postman/FacePlugin-API.postman_collection.json.

Default base URL: http://127.0.0.1:8083

Canonical protocol: /api/* (see FacePlugin Protocol). No version segment in route paths.

Demo UI (Gradio) — local only

The Docker image is API/SDK server only (no Gradio). For a simple browser test UI 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.py

Open 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. Examples load every file under assets/examples/samples/ (all face(*) sample images and all pair(*)_1 / pair(*)_2 pairs).

About SDK

Use the Python bindings in sdk.py. Return code 0 means success.

1. Initializing the SDK

Step One

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.…

Step Two

Next, activate the SDK with the path to your license file (license.txt containing FP1.…, or legacy license.dat).

ret = sdk.activate("license.txt")

If activation is successful, the return value will be 0. Otherwise, an error value will be returned.

Step Three

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.

2. APIs

Detect

result = sdk.detect(base64_image, crop_image=False)

Quality

result = sdk.quality(base64_image, crop_image=False)

Feature

result = sdk.feature(base64_image)

Match

result = sdk.match(base64_image1, base64_image2, crop_image=False)

Similarity

result = sdk.similarity(feature1_b64, feature2_b64)

List of our Products

Contact

Name		Name	Last commit message	Last commit date
assets		assets
lib		lib
postman		postman
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
app.py		app.py
build_docker.sh		build_docker.sh
demo.py		demo.py
demo_ui.py		demo_ui.py
docker-compose.gpu.yml		docker-compose.gpu.yml
docker-compose.yml		docker-compose.yml
license.txt.example		license.txt.example
license_ux.py		license_ux.py
requirements-demo.txt		requirements-demo.txt
requirements.txt		requirements.txt
run.sh		run.sh
sdk.py		sdk.py

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

🌐 Company Site - Here

🤗 Hugging Face - Here

🛟 Help Center - Here

🐳 Docker Hub - Here

Face Recognition SDK — Linux / Docker (Fully On-Premise)

Introduction

◾ Main Functionalities

◾ Product List

Before you start

System requirements

Download runtime libraries (lib folder)

Where to download

How to Download Dependencies into ./lib/

Start the API

Option A — Docker Hub (no Drive download)

Option B — Building locally with Docker Compose

Option C — Native Linux setup (No Docker)

SDK License

How to get a license

Please contact us

Try it

Health

Documentation

Postman

Demo UI (Gradio) — local only

About SDK

1. Initializing the SDK

Step One

Step Two

Step Three

2. APIs

Detect

Quality

Feature

Match

Similarity

List of our Products

Contact

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

How to Download Dependencies into `./lib/`