Note

Hello, welcome to the SunFounder Raspberry Pi & Arduino & ESP32 Enthusiasts Community on Facebook! Dive deeper into Raspberry Pi, Arduino, and ESP32 with fellow enthusiasts.

Why Join?

  • Expert Support: Solve post-sale issues and technical challenges with help from our community and team.

  • Learn & Share: Exchange tips and tutorials to enhance your skills.

  • Exclusive Previews: Get early access to new product announcements and sneak peeks.

  • Special Discounts: Enjoy exclusive discounts on our newest products.

  • Festive Promotions and Giveaways: Take part in giveaways and holiday promotions.

👉 Ready to explore and create with us? Click [here] and join today!

Note

If you are using the pre-installed “Raspberry Pi OS with AI Fusion Lab Kit” image, you can skip this section. This image already includes all the software installations, environment configurations, and example code deployments described in this chapter.

0. Setup MediaPipe

About the OS Version

Warning

Recommended OS: Raspberry Pi OS Bookworm (Debian 12, 64-bit)

Raspberry Pi OS Trixie (Debian 13) is not recommended because:

  • MediaPipe does not yet support Python 3.13.

  • Picamera2 only works with the system Python.

This tutorial will be updated once Trixie becomes supported.

If you would like to request official MediaPipe support for Python 3.13, you can submit feedback here:

Before You Start

Important

Before you start, make sure:

  • The pan-tilt is assembled

  • You can access the Raspberry Pi desktop

  • The code package is installed

  • Fusion HAT+ is installed and configured

  • OpenCV is installed

For detailed instructions, see 0. Setup OpenCV.

These preparations ensure MediaPipe can run with full graphical and camera functionality on your Raspberry Pi.

Installation Steps

  1. Install MediaPipe

    Install MediaPipe using pip. On Raspberry Pi OS Bookworm (Debian 12, 64-bit), pip will download the correct wheel automatically.

    sudo pip install mediapipe --break-system-packages

  2. Verify the installation

    Run the following command to confirm that MediaPipe is installed correctly.

    python3 - <<EOF
import mediapipe as mp
print("MediaPipe version:", mp.__version__)
EOF

    Expected output:

    MediaPipe version: 0.10.18

Common Issues & Solutions

  1. MediaPipe installation fails

    This usually happens when using an unsupported OS version.

    Solution:

    • MediaPipe currently works only on Raspberry Pi OS Bookworm (Debian 12, 64-bit).

    • Raspberry Pi OS Trixie (Debian 13, Python 3.13) is not supported.

  2. Camera cannot be opened in MediaPipe or OpenCV

    This usually happens when the Raspberry Pi camera interface is not enabled.

    Solution:

    • Enable the camera in raspi-config: Interface Options → Camera → Enable

  3. OpenCV import errors

    Some pip-installed versions of OpenCV may be incompatible with Raspberry Pi OS libraries.

    Solution:

    sudo apt install python3-opencv

  4. MediaPipe cannot be imported after installation

    This may happen if pip, setuptools, or wheel are outdated.

    Solution:

    sudo pip install --upgrade pip setuptools wheel

Your MediaPipe is now ready. You can proceed to the next section to run real-time face detection using the Raspberry Pi camera.