Skip to content

How to install odio on a Raspberry Pi or Debian

Two ways to install odio, same result: same packages, same services, same configuration. On a Raspberry Pi, flash a ready-made image. On an existing Debian 13 (trixie) or Ubuntu system, run the installer.

  1. Install and open Raspberry Pi Imager.

  2. Go to Options App → Content Repository → Use custom URL, and paste this URL:

    https://odio.love/odio.rpi-imager-manifest
  3. Select odio in the operating system list. It is available for armhf (32-bit) and arm64 (64-bit) boards.

    Raspberry Pi Imager showing odio images available for arm64 and armhf architectures

  4. In the Imager settings, configure the hostname, SSH, and WiFi if needed.

    Ethernet is recommended over WiFi for reliable audio streaming.

  5. Flash the SD card, put it in the Pi and power it on. Your Pi boots ready.

  6. Open the web UI from any browser on your network:

    http://<hostname>.local:8018/ui
HardwareArchitectureInstall methodTested on
Raspberry Pi B, B+armv6lImager, installerRaspberry Pi OS Lite (Trixie)
Raspberry Pi Zero Warmv6lImager, installer—
Raspberry Pi 2armv7Imager, installerRaspberry Pi OS Lite (Trixie)
Raspberry Pi 3B+armv7 / arm64Imager, installerRaspberry Pi OS Lite (Trixie)
Raspberry Pi 4, 5arm64Imager, installer—
Raspberry Pi Zero 2 Warm64Imager, installer—
Radxa Zero 3Warm64installerDebian 13 (Trixie)
Desktopx86-64installerDebian 13 Gnome
NASx86-64installerOpenMediaVault 8

For sound output, any DAC HAT supported by the kernel and any USB DAC work, see DAC and overclocking.

The Radxa Zero 3W was tested by @afuessl in odios#105, with a USB SPDIF interface as sound output. Thanks!

The installer is idempotent, re-run it to upgrade an existing installation. Each node shows available updates in its SSH MOTD (since 2026.4.1rc1), and upgrades can be checked and applied straight from Home Assistant or the web UI (since 2026.6.0b2). See Upgrade for the full flow.

Every DAC HAT supported by the Raspberry Pi kernel works with odio, generic I2S DACs included. Pick yours from the settings page and reboot (since 2026.9.0b1). It writes the dtoverlay line to /boot/firmware/config.txt and turns the onboard audio off. On older releases, edit the file by hand with the overlay from your HAT manufacturer’s documentation.

A USB DAC needs none of that, no overlay and no settings page: plug it in and it shows up under Audio Server › Default Sink in the web UI.

Overclocking stays a manual edit in the same file:

# Overclock (useful on older armhf boards like Pi B+ at 700MHz)
arm_boost=1
arm_freq=800

Once installed, your odio node is controllable from:

  • Embedded web UI — built into the API, accessible from any browser on your network.
  • Settings page — upgrades, components, and the audio HAT, behind the gear icon of the web UI.
  • odio application — web app installable from your browser, manage all your nodes from one place.
  • Home Assistant — native integration from the Home Assistant Marketplace. Every feature exposed as HA entities.
  • Any MPD client — for library browsing and playback control.
  • The REST API — for automation, scripting, or building your own client.

For a deeper look at how the stack is put together, see How it works.

odio started as a personal setup in 2020 — a Raspberry Pi wired to a stereo amplifier, replacing a pile of dedicated devices with a single board. After years of daily use and iteration, odio packages that setup for anyone to use. Every component is independent and can be set up from scratch individually.

The full journey that led to odio is documented on Medium.