Mopidy-Iris

Last reviewed Sep 13, 2026 · 796 words

Iris is a face, Mopidy is the body, and Snapcast is the speakers. That is the entire architecture, and the reason most people who install Iris are disappointed is that they expected the face to come with a body. Mopidy is a Python music server that plays local files and streaming backends through GStreamer and exposes an MPD protocol and a JSON-RPC web API; Iris is a Mopidy extension that serves a modern, responsive web UI on top of it at http://host:6680/iris/. Install Iris alone and you get an empty library and no sound. Install the three together and you get a self-hosted, multi-room player that beats the Sonos app on the axes a self-hoster cares about.

Getting Mopidy first

Mopidy is packaged for Debian and Raspberry Pi OS from the project's apt repository, and it runs as a system service with config in /etc/mopidy/mopidy.conf. Add backends as extensions: Mopidy-Local for files on disk, Mopidy-Jellyfin if your library already lives in Jellyfin, Mopidy-YouTube, Mopidy-SoundCloud, Mopidy-Tidal, and the streaming services that survive. Each is a pip package and a config section. The important defaults are port 6680 for HTTP and 6600 for MPD, and the audio output line, which on a Pi is where most first-day problems live. The Mopidy entry covers the server on its own; this guide assumes it plays something to a speaker before Iris goes on.

Installing Iris

sudo python3 -m pip install Mopidy-Iris
sudo sh -c 'echo "mopidy ALL=NOPASSWD: /usr/local/lib/python3*/dist-packages/mopidy_iris/system.sh" >> /etc/sudoers'
sudo systemctl restart mopidy

The sudoers line is optional and slightly ugly. It lets Iris trigger a local library rescan and a Mopidy restart from its settings page rather than from a shell, which is the difference between a household appliance and a thing only you can maintain. Then open port 6680 in the browser: the UI has a library browser, search across every backend, a queue with drag reordering, playlists that can mix sources, album art fetched from the backends and from LastFM if you add a key, and a settings page where each backend shows its own status. On a Pi 3 with 128 MB free it is responsive; on anything newer it feels like a native app, and it installs as a PWA on phones.

Spotify is the honest disappointment

Iris's most-cited backend is Mopidy-Spotify, and it is the one to be careful about. Spotify removed the libspotify library the extension was built on in 2022; the rewritten version uses a GStreamer plugin and a Premium account, and the feature set has varied release to release, with browsing and playlist support that has come back only partially. It works for playback at last check, but expect breakage after Spotify-side changes and check the extension's issue tracker before building a household around it. Local files, Jellyfin, YouTube and Tidal are the backends that do not surprise you.

Snapcast turns it into multi-room

Mopidy plays to one output. Point that output at a Snapcast server with a snapfifo sink in the audio section, run a Snapcast client on each Pi or speaker, and every room plays in sync within a millisecond. Iris has a Snapcast panel that lists groups and clients with per-client volume and mute, which is what makes it the household remote rather than a developer tool. It is the cheapest sync-audio setup that exists: 3 Pi Zeros and a USB DAC each is well under 100 dollars for three rooms.

When Navidrome or Music Assistant is the better pick

If your library is local files and you want an app on your phone, Navidrome is simpler: one binary, Subsonic API, dozens of native clients, and no GStreamer to debug; the Navidrome guide is the shorter path. If your goal is playing to Sonos, Chromecast and Home Assistant speakers, Music Assistant is the project that grew past this stack and is the bigger, safer bet. Iris wins for a single home server driving wired or Snapcast speakers from mixed sources, controlled from a browser on the wall or a phone.

What I'd do

Mopidy from the apt repo on a Pi 4, Mopidy-Local plus Mopidy-Jellyfin as backends, Iris with the sudoers line so the family can rescan, and Snapcast for the rooms you care about. Skip Spotify unless you accept the maintenance. It is a "Medium" project because of the three moving parts, and once they agree it runs unattended for years on 128 MB of RAM, which is more than the Sonos app has ever offered.