Skip to main content

​
Overview

Deploying YOLO-Pi on Raspberry Pi requires building an ARM-compatible Docker image with TensorFlow support. This process is resource-intensive and requires special preparation.
Building the Docker image on Raspberry Pi 3 takes several hours (potentially 6-12 hours). Plan accordingly and use a screen session to allow disconnecting during the build.

​
Prerequisites

  • Raspberry Pi 3 (or newer) with Raspbian Stretch
  • 2GB+ USB drive for swap space
  • Camera module or USB camera
  • At least 8GB SD card with 2-3GB free space
  • Stable internet connection

​
Setting Up Swap Space

Raspberry Pi’s limited RAM requires additional swap space to compile the Docker image.
1

Prepare USB drive

Insert a 2GB+ USB drive and identify it (usually /dev/sda):
lsblk
Create a partition and format it:
sudo fdisk /dev/sda
# Press 'n' for new partition, then 'w' to write

sudo mkfs.ext4 /dev/sda1
2

Mount the USB drive

Create a mount point and mount the drive:
sudo mkdir /usb
sudo mount /dev/sda1 /usb
3

Configure automatic mounting

Edit /etc/fstab to mount the USB drive on boot:
sudo nano /etc/fstab
Add this line:
/dev/sda1	/usb	ext4	defaults 0 0
Mount all filesystems:
sudo mount -a
4

Configure swap file

Edit the swap configuration:
sudo nano /etc/dphys-swapfile
Comment out existing CONF_SWAPFILE and CONF_SWAPSIZE lines and add:
CONF_SWAPFILE=/usb/swap
CONF_SWAPSIZE=2048
5

Create and enable swap

Recreate the swap file and enable it:
sudo dphys-swapfile setup
sudo dphys-swapfile swapon
Verify swap is active:
free -h

​
Building the Docker Image

1

Start a screen session

Use screen to prevent interruption if SSH disconnects:
screen -S docker-build
To detach from screen: Press Ctrl+A, then DTo reattach: screen -r docker-build
2

Prepare build directory

Create a build directory and copy the Dockerfile:
mkdir -p ~/src
cd ~/src
Copy Dockerfile.rpi to this directory as Dockerfile.
3

Download TensorFlow wheel

Download the pre-compiled TensorFlow binary for ARM and rename it:
wget https://github.com/samjabrahams/tensorflow-on-raspberry-pi/releases/download/v1.1.0/tensorflow-1.1.0-cp34-cp34m-linux_armv7l.whl

mv tensorflow-1.1.0-cp34-cp34m-linux_armv7l.whl \
   tensorflow-1.1.0-cp35-cp35m-linux_armv7l.whl
The Dockerfile uses Python 3.5 (cp35), but the pre-compiled wheel is tagged for Python 3.4 (cp34). Renaming allows pip to install it for Python 3.5.
4

Build the Docker image

Start the build process:
docker build -t ashya/yolo-pi .
This will take several hours. Monitor progress periodically but expect long compilation times, especially for OpenCV.
The build process:
  • Installs system dependencies
  • Installs NumPy, Keras 2.1.2, h5py, and paho-mqtt
  • Installs TensorFlow 1.1.0 from the wheel file
  • Compiles OpenCV 3.3.0 from source
  • Copies application code
5

Verify the build

Once complete, verify the image:
docker images | grep yolo-pi

​
Running on Raspberry Pi

​
Interactive Mode

Run interactively for testing: 
docker run -it --rm --device /dev/video0 ashya/yolo-pi /bin/bash

​
Daemon Mode

Run as a background service: 
docker run -d --device /dev/video0 \
  -e MQTT=<mqtt-server-ip> \
  --restart unless-stopped \
  --name yolo-pi \
  ashya/yolo-pi
  • -d: Run in detached (daemon) mode
  • --device /dev/video0: Grant access to camera
  • -e MQTT=<mqtt-server-ip>: Set MQTT broker address
  • --restart unless-stopped: Auto-restart on failure or reboot
  • --name yolo-pi: Name the container for easy management

​
Running Automatically on Boot

1

Ensure Docker starts on boot

Enable Docker service:
sudo systemctl enable docker
2

Create container with restart policy

Use the --restart unless-stopped flag when creating the container:
docker run -d --device /dev/video0 \
  -e MQTT=192.168.1.100 \
  --restart unless-stopped \
  --name yolo-pi \
  ashya/yolo-pi
3

Verify auto-start

Reboot and check that the container starts:
sudo reboot
# After reboot:
docker ps

​
Managing the Container

​
View logs

docker logs -f yolo-pi

​
Stop the container

docker stop yolo-pi

​
Start the container

docker start yolo-pi

​
Restart the container

docker restart yolo-pi

​
Remove the container

docker rm -f yolo-pi

​
Performance Considerations

YOLO-Pi on Raspberry Pi 3 processes approximately 1 frame every 2 seconds using the tiny-yolo-voc model. This is expected behavior given the hardware constraints.

​
Optimization Tips

  • Use the tiny-yolo-voc model (smaller and faster than full YOLO)
  • Reduce camera resolution if needed
  • Ensure adequate cooling (heatsinks or fan)
  • Use a high-quality power supply (2.5A minimum)

​
Troubleshooting

Ensure swap is properly configured and active:
free -h
swapon --show
You should see 2GB of swap space. If not, repeat the swap setup steps.
This is often due to insufficient resources. Ensure:
  • Swap space is active (2GB)
  • No other heavy processes are running
  • SD card has at least 2GB free space
If it continues to fail, try building on a more powerful machine using cross-compilation.
For Raspberry Pi Camera Module, ensure it’s enabled:
sudo raspi-config
# Navigate to Interface Options > Camera > Enable
For USB cameras, verify the device:
ls -la /dev/video*
Ensure you’ve renamed the wheel file correctly to match Python 3.5. The filename must be exactly:
tensorflow-1.1.0-cp35-cp35m-linux_armv7l.whl

​
Image Details

The Raspberry Pi Docker image includes:
  • Base Image: resin/rpi-raspbian:stretch
  • OpenCV: 3.3.0 compiled for ARM (without AVX/CUDA)
  • TensorFlow: 1.1.0 (pre-compiled ARM wheel)
  • Keras: 2.1.2
  • MQTT Client: paho-mqtt
  • Additional Libraries: NumPy, h5py 2.7.1, scipy, PIL

​
Next Steps

Production Setup

Learn about production deployment best practices

Running Inference

Learn how to run and configure inference

Build docs developers (and LLMs) love

Get started for freeTalk to us