Skip to content
odioodio docs

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

Compatible hardware

Section titled “Compatible hardware”
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—
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.

Upgrade

Section titled “Upgrade”

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.

DAC and overclocking

Section titled “DAC and overclocking”

Every DAC HAT supported by the Raspberry Pi kernel works with odio, generic I2S DACs included. Pick yours from the settings page on port 8021 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 DAC manufacturer’s documentation.

USB DACs need no configuration: plug one in and it shows up as an output in the PulseAudio section of 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

Next steps

Section titled “Next steps”

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 DAC selection on port 8021, linked from the web UI header.
  • odio application — web app installable from your browser, manage all your nodes from one place.
  • Home Assistant — native integration via HACS. 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.

Why odio?

Section titled “Why odio?”

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.