Running TensorFlow on Raspberry Pi 5: TFLite Setup, Code, and Debugging

The Verdict: Board and Framework Selection

If you are trying to run full desktop TensorFlow on a Raspberry Pi, stop. The full tensorflow pip package is bloated, pulls in heavy x86 GPU dependencies that fail to compile on ARM64, and will choke your Pi's RAM. For edge inference, you need TensorFlow Lite (TFLite).

Here is the decision matrix for selecting your hardware and software stack based on your frame-rate requirements and budget:

Hardware BOM and Interface Mapping

Before writing code, ensure your physical layer is correct. The Pi 5 changed the CSI camera connector to a smaller 22-pin pitch, requiring a specific cable.

Parts List

• Compute: Raspberry Pi 5 (8GB) - ~$80
• Optics: Raspberry Pi Camera Module 3 (Standard or Wide) - ~$25
• Accelerator (Optional): Google Coral USB Accelerator - ~$35
• Power: Official 27W USB-C PD Power Supply (Crucial for Pi 5 + USB peripherals) - ~$12
• Interconnect: Pi 5 specific 22-pin to 15-pin CSI ribbon cable (usually included with Camera 3) - ~$5
• Storage: 64GB NVMe SSD via M.2 HAT+ (Highly recommended over SD cards for heavy read/write logging) - ~$45

Interface and Pin Mapping

The Camera Module 3 uses the MIPI CSI-2 interface for high-speed image data, but relies on I2C for sensor configuration (focus, exposure). The Coral USB uses standard USB 3.0.

Environment Setup on Pi OS Bookworm

Raspberry Pi OS Bookworm introduced PEP 668, marking the system Python as "externally managed." If you try to run pip install tflite-runtime globally, it will fail. You must use a virtual environment.

1. Flash the OS: Use Raspberry Pi Imager to flash Raspberry Pi OS (64-bit) to your NVMe drive or SD card. Enable SSH and set your username in the advanced settings.
2. Update System Packages:

   sudo apt update && sudo apt full-upgrade -y
   sudo apt install -y python3-venv python3-pip libgl1 libglib2.0-0

3. Create and Activate Virtual Environment:

   mkdir ~/tflite-vision && cd ~/tflite-vision
   python3 -m venv venv
   source venv/bin/activate

4. Install Dependencies:

   pip install --upgrade pip
   pip install tflite-runtime opencv-python-headless numpy picamera2

   Note: We use opencv-python-headless to avoid pulling in heavy GUI dependencies that cause compilation errors on headless Pi setups.

5. Download a TFLite Model:

   wget https://storage.googleapis.com/download.tensorflow.org/models/tflite/mobilenet_v1_1.0_224_quant_and_labels.zip
   unzip mobilenet_v1_1.0_224_quant_and_labels.zip -d model/

Complete TFLite Inference Code

This script initializes the Pi Camera Module 3 using the modern picamera2 library (which wraps libcamera), captures a frame, preprocesses it for the MobileNetV1 input tensor, runs inference, and prints the top prediction. It includes robust error handling for hardware and model initialization.

import time
import cv2
import numpy as np
from picamera2 import Picamera2
from tflite_runtime.interpreter import Interpreter

# --- Configuration & Pin Definitions ---
# Camera resolution must be >= model input size
CAM_WIDTH = 640
CAM_HEIGHT = 480
MODEL_PATH = "model/mobilenet_v1_1.0_224_quant.tflite"
LABELS_PATH = "model/labels.txt"

def load_labels(path):
    """Load labels from file."""
    with open(path, 'r', encoding='utf-8') as f:
        return [line.strip() for line in f.readlines()]

def preprocess_image(image, target_size):
    """Resize and normalize image for TFLite input."""
    resized = cv2.resize(image, target_size)
    # MobileNet quantized models expect uint8 [0, 255]
    return np.expand_dims(resized, axis=0).astype(np.uint8)

def main():
    print("[INFO] Initializing Pi Camera Module 3...")
    try:
        picam2 = Picamera2()
        config = picam2.create_preview_configuration(
            main={"size": (CAM_WIDTH, CAM_HEIGHT), "format": "RGB888"}
        )
        picam2.configure(config)
        picam2.start()
        time.sleep(2)  # Allow camera sensor to warm up and adjust AWB
    except RuntimeError as e:
        print(f"[FATAL] Camera initialization failed: {e}")
        print("Check CSI ribbon cable seating and run 'libcamera-hello' to test.")
        return

    print("[INFO] Loading TFLite model...")
    try:
        interpreter = Interpreter(model_path=MODEL_PATH)
        interpreter.allocate_tensors()
    except (ValueError, RuntimeError) as e:
        print(f"[FATAL] Model load failed: {e}")
        return

    input_details = interpreter.get_input_details()
    output_details = interpreter.get_output_details()
    
    # Extract input shape (usually [1, 224, 224, 3])
    _, input_height, input_width, _ = input_details[0]['shape']
    labels = load_labels(LABELS_PATH)

    print("[INFO] Starting inference loop. Press Ctrl+C to exit.")
    try:
        while True:
            # Capture frame as numpy array
            frame = picam2.capture_array()
            
            # Preprocess
            input_data = preprocess_image(frame, (input_width, input_height))
            
            # Run Inference
            start_time = time.time()
            interpreter.set_tensor(input_details[0]['index'], input_data)
            interpreter.invoke()
            inference_time = time.time() - start_time
            
            # Parse Output
            output_data = interpreter.get_tensor(output_details[0]['index'])
            results = np.squeeze(output_data)
            top_index = np.argmax(results)
            top_confidence = results[top_index] / 255.0  # Dequantize uint8 to float
            
            if top_confidence > 0.4:  # Confidence threshold
                label = labels[top_index] if top_index < len(labels) else "Unknown"
                print(f"Detected: {label} | Confidence: {top_confidence:.2f} | Time: {inference_time*1000:.1f}ms")
            
            time.sleep(0.1) # Throttle loop to ~10 FPS to save CPU
            
    except KeyboardInterrupt:
        print("\n[INFO] Stopping camera and exiting.")
    finally:
        picam2.stop()

if __name__ == "__main__":
    main()

Debugging: The Top 3 TensorFlow Pi Errors

When your build fails, do not guess. Follow this decision path. The first three things to check when any Pi vision script crashes:

1. Is the virtual environment active? (Look for (venv) in your terminal prompt).
2. Is the OS 64-bit? Run uname -m. If it returns armv7l, you are on 32-bit OS and TFLite wheels will fail. You need aarch64.
3. Is the camera hardware locked? Run libcamera-hello. If it fails, no Python script will work. Fix the hardware layer first.

If those pass, look for these exact error strings:

Error 1: The PEP 668 Blocker

Exact String: error: externally-managed-environment
Context: Occurs when running pip install tflite-runtime outside a virtual environment on Pi OS Bookworm.

• Cause 1 (Most Likely): You forgot to create or activate your venv.
• Cause 2: You are running an automated script via sudo, which drops you out of the user's virtual environment.
• Fix: Run source ~/tflite-vision/venv/bin/activate. Never use sudo pip. If a service needs to run at boot, point the systemd service file directly to the venv python binary: ExecStart=/home/pi/tflite-vision/venv/bin/python /home/pi/tflite-vision/script.py.

Error 2: The Missing GL Library

Exact String: ImportError: libGL.so.1: cannot open shared object file: No such file or directory
Context: Occurs on the import cv2 line.

• Cause 1 (Most Likely): You installed the standard opencv-python instead of opencv-python-headless, and the Pi lacks a desktop environment or GL libraries.
• Cause 2: You are on a headless Lite OS and missing underlying system dependencies.
• Fix: Run sudo apt install libgl1. Alternatively, uninstall the heavy version (pip uninstall opencv-python) and install the headless version (pip install opencv-python-headless).

Error 3: The Tensor Dimension Mismatch

Exact String: ValueError: Cannot set tensor: Dimension mismatch. Got 1, expected 3 for input 0
Context: Occurs on the interpreter.set_tensor() line.

• Cause 1 (Most Likely): You passed a 2D image array directly to the interpreter without adding the batch dimension.
• Cause 2: Your camera output format is grayscale (1 channel) but the model expects RGB (3 channels).
• Fix: Ensure your preprocessing function includes np.expand_dims(image, axis=0) to add the batch dimension, and verify your picamera2 configuration is set to "format": "RGB888" to guarantee 3 color channels.

Scaling the Build: Simplify or Extend

Once the baseline inference loop is running, you need to decide how to adapt it for your specific application.

How to Simplify the Build

If you are deploying this to a Pi Zero 2 W or need to maximize battery life on a portable rig:

• Drop the GUI: Ensure you are running Raspberry Pi OS Lite (no desktop). This frees up ~300MB of RAM and stops the X server from stealing CPU cycles.
• Downsample Early: Change the picamera2 configuration to capture directly at 224x224. The Pi 5's hardware ISP will do the downscaling in silicon before the frame ever hits system RAM, dropping your CPU load to near zero.
• Use Microcontrollers for Actuation: Don't run servos directly off the Pi's GPIO. Offload PWM generation to an Arduino Nano or ESP32 via I2C to prevent kernel jitter from stalling your inference loop.

How to Extend the Build

If you need production-grade performance or smart home integration:

• Add the Coral USB Delegate: Modify the interpreter initialization to use the Edge TPU.

  from tflite_runtime.interpreter import load_delegate
  interpreter = Interpreter(
      model_path=MODEL_PATH,
      experimental_delegates=[load_delegate('libedgetpu.so.1')]
  )

  Note: You must compile or download an Edge TPU compatible model (usually ending in _edgetpu.tflite).
• Integrate MQTT: Add the paho-mqtt library to your venv. Publish the top_index and top_confidence to a local Mosquitto broker. This allows Home Assistant to trigger automations (e.g., turning on the porch light if a "person" is detected with >80% confidence) without the Pi needing to run the entire smart home stack.
• Switch to Task Library: For complex object detection (bounding boxes) rather than simple classification, migrate from the raw Interpreter to the TFLite Task Vision API. It handles anchor box decoding and NMS (Non-Maximum Suppression) natively in C++, saving you from writing hundreds of lines of fragile numpy math.