pyzk

0.9 verified Fri May 01 auth: no python

An unofficial Python library for interacting with ZKTeco fingerprint devices (attendance machines, access control). Version 0.9 is the latest stable release; development appears slow with no recent updates. The library supports TCP/IP communication and provides basic operations like connect, disconnect, get/set user data, and read real-time logs.

pip install pyzk

Common errors

error pyzk.core.ZKError: Unable to connect to device ↓

cause Device unreachable, wrong IP/port, or firewall blocking.

fix

Verify network connectivity (ping), correct IP and port, and that the device is powered on. Try setting force_udp=True or verbose=True for debugging.

error pyzk.core.ZKError: Device communication error ↓

cause Protocol mismatch or unsupported device model.

fix

Ensure your device is a ZKTeco model that uses the standard protocol. Try upgrading the device firmware or use an alternative library.

error AttributeError: 'ZK' object has no attribute 'get_users' ↓

cause Trying to call get_users() after calling get_device_info() when not connected or using a very old version.

fix

Always call connect() first and keep the connection open. For old versions, check the methods available: use get_user() with a specific user ID.

Warnings

gotcha The default port for pyzk is 4370, but many ZKTeco devices use port 4370 or 4371. Double-check your device configuration. ↓

fix Use port 4370 unless you know your device uses a different one.

gotcha The library uses a proprietary protocol. Not all ZKTeco models are supported; some newer devices may not work. ↓

fix Test with your specific device model. If it fails, consider using the official ZKTeco SDK or binary protocol libraries like zkteco.

breaking In older versions (pre-0.9), the method get_attendance() returned a list of tuples. In 0.9, it returns a list of Attendance objects with attributes like .user_id, .status, .timestamp. ↓

fix Update your code to access properties on Attendance objects instead of indexing tuples.

Imports

ZK
```
from pyzk import ZK
```

Quickstart

Connects to a ZKTeco device, prints device info, users, and attendance records.

from pyzk import ZK

conn = None
zk = ZK('192.168.1.201', port=4370, timeout=5, password=0, force_udp=False, verbose=True)
try:
    conn = zk.connect()
    print('Connected:', conn)
    print('Device info:', zk.get_device_info())
    users = zk.get_users()
    for user in users:
        print(user)
    attendances = zk.get_attendance()
    for att in attendances:
        print(att)
except Exception as e:
    print('Error:', e)
finally:
    if conn:
        conn.disconnect()