Guide: Compiling Custom YOLOv8 HEFs on Non-Ubuntu Linux Using Docker (No Shell Script)

General Discussion
, , ,
1

I’ve been working through the process of compiling custom-trained YOLOv8 models into HEF files for the Hailo-8L, and I hit several undocumented issues along the way. I’ve written up a guide that covers the workarounds, which I hope saves others some time.

The situation: I’m building an AI security camera system using a Pi 5 + Hailo-8L AI HAT+, running custom YOLOv8 models trained with Ultralytics. My compilation workstation runs Linux Mint (not Ubuntu) and doesn’t have a physical Hailo device installed.

The problem: The official hailo_ai_sw_suite_docker_run.sh script probes for PCIe drivers and nvidia-docker, which fails on a workstation without Hailo hardware. The Ubuntu requirement in Hailo’s docs is for that shell script, not for Docker itself.

The solution: Bypass the shell script entirely with a direct docker run command. The DFC runs on CPU inside the container — no GPU, no PCIe driver, no nvidia-docker needed on the host.

The gotchas I found (and their fixes)

1. UID mismatch on the Docker volume mount

The hailo user inside the container runs as UID 10642. Your host user is typically UID 1000. Result: the container can read your mounted files but can’t write to them. You get “Permission denied” errors, and compilation output may not be accessible from the host.

Fix: On the host, after first container run:

bash

sudo chown -R 10642:10600 ~/hailo_compile

2. Model Zoo calibration data download fails silently

Running hailomz compile yolov8n --hw-arch hailo8l downloads the model ONNX successfully but the COCO calibration dataset download fails without a clear error. Compilation then crashes with:

FileNotFoundError: Couldn't find dataset in /local/shared_with_docker/.hailomz/models_files/coco/2021-06-18/coco_calib2017.tfrecord

Fix: Download COCO val2017 images manually and use --calib-path:

bash

cd /local/shared_with_docker
mkdir -p calib_coco && cd calib_coco
wget http://images.cocodataset.org/zips/val2017.zip
unzip val2017.zip && mv val2017/* . && rmdir val2017 && rm val2017.zip

3. --yaml flag needs the full path

Using --yaml yolov8n.yaml gives ValueError: cfg file is missing. You need the full path inside the container:

bash

--yaml /local/workspace/hailo_model_zoo/hailo_model_zoo/cfg/networks/yolov8n.yaml

Find it with: find /local/workspace/hailo_model_zoo -name "yolov8n.yaml"

The working Docker command

bash

docker run -it \
    --name hailo_compile \
    -v ~/hailo_compile:/local/shared_with_docker \
    hailo8_ai_sw_suite_2025-10:1

No --privileged, no --gpus, no -v /dev:/dev. Just Docker and a volume mount.

The working compile command (custom model)

bash

hailomz compile yolov8n \
    --ckpt /local/shared_with_docker/models/best.onnx \
    --calib-path /local/shared_with_docker/calib/ \
    --yaml /local/workspace/hailo_model_zoo/hailo_model_zoo/cfg/networks/yolov8n.yaml \
    --hw-arch hailo8l \
    --classes <YOUR_CLASS_COUNT>

Full guide

I’ve written up the complete end-to-end workflow (training → ONNX export → calibration → Docker setup → compilation → Pi deployment) as a GitHub Gist:

This is part of my open-source AI security camera project: https://github.com/mi0iou/ai-security-camera

Tested with Hailo AI SW Suite 2025-10, Docker 28.x on Linux Mint. Hope it helps someone — happy to answer questions.

2 Likes
2

Thanks @Thomas_Herbison for providing this useful guide, and great work!

1 Like