Raspberry Pi Face Recognition Lock: Pi 5 Build, Code, and Debug Guide

Building a reliable Raspberry Pi face recognition access system in 2026 requires moving past outdated Pi 4 tutorials. The Raspberry Pi 5 (8GB variant) running Bookworm OS is now the baseline for running local convolutional neural networks (CNNs) without an external neural processing unit (NPU). To get this working on your bench, you need the Pi 5 8GB, the Camera Module 3, Python's face_recognition library, and gpiozero for safe lock control.

This guide provides the exact bill of materials, the modern Bookworm-compatible wiring and code, and a debugging matrix for the specific errors that trip up builders migrating from older Pi generations.

Hardware Spec Sheet & Parts List

Face recognition is memory-hungry. The dlib library underlying the face_recognition module will easily consume 2GB to 3GB of RAM just loading the CNN model and caching face encodings. If you use a 4GB board, the Linux OOM (Out of Memory) killer will terminate your Python script the moment a second face enters the frame.

Wiring the Camera and Relay Lock

The Pi 5 uses a smaller, higher-density MIPI CSI connector than the Pi 4. Ensure you are using the specific 15-pin to 22-pin ribbon cable included with the Pi 5, not an old Pi 4 cable. For the relay, we use GPIO 17 (Physical Pin 11). We wire the relay's VCC to the 5V pin, not 3.3V, to ensure the optocoupler LED fires reliably.

The Python Face Recognition Script

This code targets the Raspberry Pi 5 (8GB) running Raspberry Pi OS Bookworm. It uses gpiozero (the modern standard, as RPi.GPIO is deprecated on Pi 5) and OpenCV's V4L2 backend to interface with the Camera Module 3 without relying on the removed legacy camera stack.

Prerequisites: Run sudo apt install libcamera-v4l2 and pip install face_recognition opencv-python-headless gpiozero in a virtual environment.

import cv2
import face_recognition
import numpy as np
import time
import sys
import os
from gpiozero import OutputDevice

# --- PIN DEFINITIONS ---
RELAY_PIN = 17  # GPIO 17 (Physical Pin 11)

# Initialize Relay (Active LOW for standard optocoupler relay modules)
# initial_value=False means the relay is OPEN (lock is engaged) on boot
lock_relay = OutputDevice(RELAY_PIN, active_high=False, initial_value=False)

# --- CONFIGURATION ---
KNOWN_FACES_DIR = './known_faces'
TOLERANCE = 0.55  # Lower = stricter matching (0.6 is default)
UNLOCK_DURATION = 5.0  # Seconds to keep the door unlocked
FRAMERATE_LIMIT = 0.2  # Process every 5th frame to save CPU

def load_known_faces(directory):
    known_encodings = []
    known_names = []
    if not os.path.exists(directory):
        print(f'Error: Directory {directory} not found.')
        return known_encodings, known_names
        
    for filename in os.listdir(directory):
        if filename.endswith(('.jpg', '.png')):
            path = os.path.join(directory, filename)
            image = face_recognition.load_image_file(path)
            encodings = face_recognition.face_encodings(image)
            if len(encodings) > 0:
                known_encodings.append(encodings[0])
                known_names.append(os.path.splitext(filename)[0])
                print(f'Loaded face: {known_names[-1]}')
            else:
                print(f'Warning: No face found in {filename}')
    return known_encodings, known_names

def main():
    known_encodings, known_names = load_known_faces(KNOWN_FACES_DIR)
    if not known_encodings:
        print('No known faces loaded. Exiting.')
        sys.exit(1)

    # Initialize Camera via V4L2 backend (Required for Pi 5 Bookworm)
    video_capture = cv2.VideoCapture(0, cv2.CAP_V4L2)
    if not video_capture.isOpened():
        print('Error: Could not open camera via V4L2. Is libcamera-v4l2 installed?')
        sys.exit(1)

    process_this_frame = 0
    last_unlock_time = 0

    try:
        while True:
            ret, frame = video_capture.read()
            if not ret:
                print('Error: Failed to grab frame.')
                time.sleep(1)
                continue

            # Downscale frame for faster processing
            small_frame = cv2.resize(frame, (0, 0), fx=0.25, fy=0.25)
            rgb_small_frame = cv2.cvtColor(small_frame, cv2.COLOR_BGR2RGB)

            process_this_frame += 1
            if process_this_frame % int(1/FRAMERATE_LIMIT) == 0:
                face_locations = face_recognition.face_locations(rgb_small_frame)
                face_encodings = face_recognition.face_encodings(rgb_small_frame, face_locations)

                for face_encoding in face_encodings:
                    matches = face_recognition.compare_faces(known_encodings, face_encoding, tolerance=TOLERANCE)
                    name = 'Unknown'

                    face_distances = face_recognition.face_distance(known_encodings, face_encoding)
                    best_match_index = np.argmin(face_distances)
                    if matches[best_match_index]:
                        name = known_names[best_match_index]
                        
                        # Trigger Lock
                        if time.time() - last_unlock_time > UNLOCK_DURATION:
                            print(f'Access Granted: {name}')
                            lock_relay.on()  # Energize relay, cut power to fail-safe lock
                            time.sleep(UNLOCK_DURATION)
                            lock_relay.off() # Re-engage lock
                            last_unlock_time = time.time()

    except KeyboardInterrupt:
        print('\nShutdown requested.')
    except Exception as e:
        print(f'Unexpected error: {e}')
    finally:
        video_capture.release()
        lock_relay.off() # Ensure lock is secured on exit
        lock_relay.close()
        print('Resources released. Door secured.')

if __name__ == '__main__':
    main()

Debugging: When the Camera or Script Fails

Migrating to the Pi 5 and Bookworm OS breaks almost every face recognition tutorial written before 2024. Here are the exact error strings you will encounter and how to fix them.

The First Three Things to Check

1. Camera Stack: The legacy picamera library is dead on Pi 5. You must use the libcamera V4L2 wrapper.
2. dlib Compilation: If face_recognition fails to install via pip, you are missing the ARM NEON compiler flags.
3. Power Sag: If the Pi reboots when the lock engages, your buck converter cannot handle the simultaneous 2.5A Pi draw and the 500mA lock drop-out current.

Error Matrix

Extending or Simplifying the Build

How to Simplify: If you only need basic face detection (knowing a human is there, but not who it is) to trigger a light, drop the face_recognition library entirely. Use OpenCV's built-in Haar Cascade classifiers (cv2.CascadeClassifier). This reduces RAM usage to under 300MB, allowing you to downgrade the hardware to a Raspberry Pi Zero 2 W and cut the BOM cost by 70%.

How to Extend: For a production-grade access control system, the Pi shouldn't switch the lock directly. Instead, wire the Pi's GPIO to the Wiegand input of a dedicated commercial access controller (like a HID or ZKTeco board). You can also integrate the Python script with Home Assistant via MQTT. When a face is recognized, publish a payload to homeassistant/sensor/frontdoor/state to log the entry event and trigger a smart home welcome routine.

Frequently Asked Questions

Can Raspberry Pi face recognition work without internet?

Yes, completely offline. The face_recognition library uses a local ResNet model (dlib) that runs entirely on the Pi's CPU. Once you have installed the Python packages and downloaded your known face images, you can disconnect the Ethernet/WiFi. In fact, running it offline is recommended for security to prevent SSH brute-force attacks on an internet-exposed door controller.

How to improve Raspberry Pi face recognition accuracy in low light?

The Camera Module 3 has decent low-light performance, but infrared (IR) illumination is the professional solution. Because the Pi Camera 3 has an IR-cut filter, you cannot just shine an IR LED at it. You have two options: buy the specific Pi Camera Module 3 NoIR variant and mount an 850nm IR LED ring around the lens, or use a standard visible-light LED ring (4000K daylight) wired to a GPIO-triggered MOSFET that turns on only when the PIR motion sensor detects a person approaching the door.

Is Raspberry Pi 5 fast enough for real-time face recognition?

It achieves roughly 4 to 8 Frames Per Second (FPS) using the default CNN model, which is more than enough for a door lock where a person stands still for 1-2 seconds. However, it is not 'real-time' in the sense of tracking a person walking quickly across a room. If you need >20 FPS for multi-person tracking, you must add the Raspberry Pi AI Kit (featuring the Hailo-8L NPU) and switch from dlib to a YOLOv8 model optimized for the Hailo runtime.