← Back to Docs

YOLOv11n to Hailo‑8 Compilation

Set up the Hailo development environment, calibrate your dataset, create configuration files, compile your model into a HEF, and deploy it on the Raspberry Pi AI Kit.
yolo hailo
1

Set Up the Hailo Development Environment

Install dependencies and the Hailo toolchain in a clean Python environment on an Ubuntu x86_64 machine.

Compiling a YOLOv11n model for the Hailo‑8 accelerator must be done on an Ubuntu machine with x86_64 architecture. These steps prepare your system by installing required packages, the Hailo SDK and the Hailo Model Zoo in a fresh Python virtual environment.

bash 
sudo apt update
sudo apt install -y python3.10 python3.10-venv python3.10-dev python3-pip \
  git wget build-essential python3-tk graphviz libgraphviz-dev

Download the Hailo wheel files from the Hailo developer portal and place them in a convenient directory (e.g., your home folder). Then create a virtual environment and install the wheels:

bash 
# Create and activate the Hailo virtual environment
python3 -m venv hailo_venv
cd hailo_venv
source bin/activate

# Upgrade pip
pip install --upgrade pip

# Install the Hailo compiler, HailoRT and model zoo wheels (replace with actual paths)
pip install ../hailo_dataflow_compiler-3.33.0-py3-none-linux_x86_64.whl
pip install ../hailort-4.23.0-cp310-cp310-linux_x86_64.whl
pip install ../hailo_model_zoo-2.17.0-py3-none-any.whl

# Clone the model zoo repository
cd ~
git clone https://github.com/hailo-ai/hailo_model_zoo.git
cd hailo_model_zoo
2

Prepare Calibration Images for Hailo

Copy a set of unlabeled images to your Hailo development machine for use during quantization calibration.

The Hailo compiler requires a small set of raw images to calibrate the quantization of your model. Use Secure Copy (scp) to transfer a few hundred images from your training dataset to the Hailo machine. Perform this step on the machine where you will run hailomz compile.

bash 
# Copy 200–1000 raw images from your dataset to the Hailo machine
scp -r data/images_raw <USER>@<HOSTNAME>:~/hailo_venv/
3

Create Hailo YOLO Configuration Files

Define the Hailo compiler configuration, post‑processing script and NMS settings required to compile your YOLOv11n model.

The Hailo compiler uses three configuration files to describe your model and post‑processing pipeline: a YAML file, a model script (.alls) and a JSON file for non‑max suppression (NMS). Create these files in your Hailo environment. Replace file paths with the correct locations on your machine.

bash 
# YAML configuration
nano yolov11n_2cls.yaml

Next create the model script:

bash 
nano y11.alls

Finally create the NMS JSON configuration:

bash 
nano yolov11n_2cls.nms.json
4

Compile the YOLOv11n Model to a Hailo HEF

Use the Hailo Model Zoo compiler to convert your fine‑tuned ONNX model into a Hailo Executable File (.hef) for deployment on the Raspberry Pi AI Kit.

With your Hailo environment activated, calibration images prepared and configuration files created, compile your model into a HEF file. The compilation process uses the calibration images to quantize the model for the Hailo‑8 hardware.

bash 
# Activate your Hailo virtual environment if not already
source ~/hailo_venv/bin/activate

# Run the Hailo compiler
hailomz compile --ckpt /home/USER/hailo_venv/yolov11n_finetune.onnx \
  --calib-path images_raw \
  --yaml /home/USER/hailo_venv/yolov11n_2cls.yaml \
  --hw-arch hailo8 \
  --model-script /home/USER/hailo_venv/y11.alls
5

Deploy the Compiled HEF to the Raspberry Pi

Copy the compiled Hailo Executable File (.hef) to your Raspberry Pi and verify it on the Hailo‑8 accelerator.

After compiling your YOLOv11n model to a .hef file, deploy it to the Raspberry Pi AI Kit. Use Secure Copy to transfer the file, then use the Hailo runtime CLI to identify the device and run inference.

bash 
# Copy the HEF file to the Pi
scp yolov11n.hef rcr@<HOSTNAME>:~

# On the Raspberry Pi, identify the Hailo‑8 device
hailortcli fw-control identify

# Run inference with the HEF file
hailortcli run yolov11n.hef
6

Hailo Environment and Compilation Troubleshooting

Resolve common issues when installing the Hailo SDK and compiling models.

When working with the Hailo SDK you may encounter environment or compilation errors. Here are solutions to common problems:

Environment Issues

  • No DNN in stream executor or InvalidArgumentError – Install a CUDNN version that matches your CUDA installation. Verify with nvcc --version and dpkg -l | grep cudnn. Use CPU mode (export CUDA_VISIBLE_DEVICES="") if necessary.
  • hailomz: command not found – Activate your virtual environment: source ~/hailo_venv/bin/activate.
  • ImportError: cannot import name 'one_of' from 'pyparsing' – Use a fresh virtual environment and install only the Hailo wheels.
  • ERROR: No matching distribution found for hailort – Install the wheel downloaded from the Hailo developer portal, not from PyPI.
  • ERROR: Requirement libgraphviz-dev not found – Install with sudo apt install libgraphviz-dev.
  • Docker containers cannot see GPUs – Install nvidia-container-toolkit and run Docker with --gpus all.
  • ImportError: libhailo.so – Ensure the Hailo SDK is installed and LD_LIBRARY_PATH includes its libraries.

Compilation Issues

  • ONNX file has only one output – Re-export the model with simplify=False and dynamic=False.
  • ValueError: None values not supported – Check that the NMS JSON matches the number of output layers.
  • invalid choice: 'hailo8' – Use the legacy AI Suite (v3/v4) when targeting Hailo‑8.
  • Poor accuracy – Provide at least 200 calibration images from your dataset.
  • No .hef produced – Look for errors earlier in the log, often due to incorrect output mappings.
  • CUDA out of memory – Reduce batch size or use CPU mode.
  • Python version mismatch – Create your virtual environment with Python 3.10.

Refer to the Hailo documentation for more detailed guidance.

Subscribe to our newsletter

The latest educational robotics news and articles, sent to your inbox weekly.