Skip to main content

​
Prerequisites

Before installing the ZKTeco Biometric Server, ensure you have:
  • Python 3.7 or higher installed on your system
  • Network access to your ZKTeco biometric devices
  • Device IP addresses and connection details
  • pip package manager (usually comes with Python)
Check your Python version with: python --version or python3 --version

​
Installation Steps

1

Clone or Download the Repository

Get the source code for the server:
git clone <repository-url>
cd zkteco-server
Or download and extract the source files manually.
2

Install Python Dependencies

The server requires the following Python packages:
PackageVersionPurpose
flask≥2.3.0Web framework for REST API
pyzk≥0.9ZKTeco device communication library
pyopenssl≥23.0.0SSL/TLS certificate generation
requests≥2.31.0HTTP client library
psycopg2-binarylatestPostgreSQL database adapter
Install all dependencies at once:
pip install -r requirements.txt
Or install individually:
pip install flask>=2.3.0 pyzk>=0.9 pyopenssl>=23.0.0 requests>=2.31.0 psycopg2-binary
If you encounter errors installing psycopg2-binary, you may need to install additional system dependencies. On Ubuntu/Debian:
sudo apt-get install libpq-dev python3-dev
3

Verify Installation

Check that all packages are installed correctly:
python -c "import flask, zk, OpenSSL, requests, psycopg2; print('All dependencies installed successfully')"
If this command runs without errors, you’re ready to proceed.
4

Configure Environment Variables

The server can be configured using environment variables. Create a .env file or set them in your shell:

​
Single Device Mode (servidor.py)

# Biometric Device Configuration
ZK_IP=192.168.1.205          # IP address of your ZKTeco device
ZK_PORT=4370                 # Port (default: 4370)
ZK_PASSWORD=0                # Device password (default: 0)
ZK_TIMEOUT=5                 # Connection timeout in seconds

# Server Configuration
API_HOST=0.0.0.0             # Bind to all interfaces
API_PORT=5000                # Server port
CERT_FILE=cert.pem           # SSL certificate file
KEY_FILE=key.pem             # SSL private key file

​
Multi-Device Mode (server.py)

# Server Configuration
API_HOST=0.0.0.0             # Bind to all interfaces
API_PORT=5000                # Server port
CERT_FILE=cert.pem           # SSL certificate file
KEY_FILE=key.pem             # SSL private key file
DEVICES_FILE=devices.json    # Device registry file
In multi-device mode, devices are managed via API endpoints rather than environment variables. The server will create a default device on first run.
5

SSL Certificate Setup

The server automatically generates self-signed SSL certificates on first run. This process happens automatically when you start the server.

​
Automatic Generation

If pyopenssl is installed and no certificates exist, the server will:
  1. Generate a 2048-bit RSA key pair
  2. Create a self-signed X.509 certificate
  3. Save cert.pem and key.pem in the working directory
  4. Certificate is valid for 365 days
You’ll see this log message:
[INFO] Certificados SSL generados.

​
Using Custom Certificates

For production environments, use certificates from a trusted Certificate Authority:
  1. Obtain your SSL certificate and private key
  2. Save them as cert.pem and key.pem (or configure custom paths)
  3. Update environment variables if using custom paths:
CERT_FILE=/path/to/your/certificate.pem
KEY_FILE=/path/to/your/privatekey.pem

​
HTTP Fallback

If pyopenssl is not installed or certificate generation fails, the server will run in HTTP mode:
[WARNING] pyopenssl no instalado. Corriendo en HTTP.
HTTP mode should only be used for testing. Always use HTTPS in production environments to encrypt sensitive biometric data.
6

Network Configuration

Ensure network connectivity between the server and biometric devices:

​
Test Device Connectivity

# Ping the device
ping 192.168.1.205

# Check if the device port is accessible
telnet 192.168.1.205 4370

​
Firewall Rules

Make sure the following ports are open:
  • 4370: ZKTeco device communication port (TCP/UDP)
  • 5000: Server API port (or your configured API_PORT)

​
Device Configuration

On your ZKTeco device:
  1. Ensure network settings are configured correctly
  2. Note the device IP address
  3. Verify the device password (default is usually 0)
  4. Enable network communication features
7

Start the Server

Launch the server using one of the implementations:
python servidor.py

​
Successful Startup

You should see output similar to:
2026-03-06 10:30:00 [INFO] Certificados SSL encontrados.
2026-03-06 10:30:00 [INFO] Dispositivos cargados: ['principal']
2026-03-06 10:30:00 [INFO] ==========================================================
2026-03-06 10:30:00 [INFO]   Servidor ZKTeco — Multi-dispositivo dinamico
2026-03-06 10:30:00 [INFO]   https://0.0.0.0:5000
2026-03-06 10:30:00 [INFO]   Dispositivos activos: 1
2026-03-06 10:30:00 [INFO]     [principal]  Entrada Principal  →  192.168.1.205:4370
2026-03-06 10:30:00 [INFO] ==========================================================
The server is now running and ready to accept requests!
8

Verify Installation

Test the server with a simple health check:
curl -k https://localhost:5000/
Expected response:
{
  "status": "online",
  "timestamp": "2026-03-06 10:30:15",
  "total_dispositivos": 1,
  "dispositivos": {
    "principal": {
      "ip": "192.168.1.205",
      "name": "Entrada Principal"
    }
  }
}

​
Test Device Connection

curl -k https://localhost:5000/device/info
If the device is reachable, you’ll receive connection details and device information.

​
Running as a Service

​
Linux (systemd)

Create a systemd service file /etc/systemd/system/zkteco-server.service: 
[Unit]
Description=ZKTeco Biometric Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/zkteco-server
Environment="ZK_IP=192.168.1.205"
Environment="API_PORT=5000"
ExecStart=/usr/bin/python3 server.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
Enable and start the service: 
sudo systemctl daemon-reload
sudo systemctl enable zkteco-server
sudo systemctl start zkteco-server
sudo systemctl status zkteco-server

​
Windows (NSSM)

Use NSSM (Non-Sucking Service Manager) to run as a Windows service: 
# Download NSSM from https://nssm.cc/
nssm install ZKTecoServer "C:\Python39\python.exe" "C:\path\to\server.py"
nssm set ZKTecoServer AppDirectory "C:\path\to\zkteco-server"
nssm start ZKTecoServer

​
Troubleshooting

​
Connection Errors

  • Verify the device IP address and port
  • Check network connectivity with ping
  • Ensure firewall rules allow traffic on port 4370
  • Verify the device password is correct
  • Use the -k flag with curl to skip verification: curl -k https://...
  • Install your certificate in the system trust store
  • Or configure your client to trust the self-signed certificate
  • Reinstall the problematic package: pip install --force-reinstall <package>
  • Check Python version compatibility
  • Try using a virtual environment to isolate dependencies
  • Ensure the server has write permissions for certificate files
  • Check permissions for devices.json in multi-device mode
  • Run with appropriate user privileges (avoid running as root)

​
Next Steps

Quickstart Guide

Get started with basic operations in 5 minutes

API Reference

Explore all available endpoints

Device Management

Configure and manage multiple devices

Configuration

Advanced configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us