Music Assistant Server: a self-hosted library manager for Home Assistant users

Who Music Assistant Server is actually for

The README describes Music Assistant as a free, open source media library manager that connects streaming services to a wide range of connected speakers. The server is the part that has to run continuously. It is not a desktop player and not a library scanner you launch when you feel like it. The project says it must run on an always-on device: a Raspberry Pi, a NAS, an Intel NUC or something similar.

The intended user is someone with more than one speaker and more than one music source. The README states the project is tailored to run side by side with Home Assistant and is meant with automation in mind. If you have a single Bluetooth speaker and one streaming account, the server adds a moving part without removing one. If you have speakers in several rooms, several services, and a Home Assistant instance that already knows about scenes and presence, the server is the piece that gives those automations something to control.

The architecture: one always-on process, many providers

The repository layout shows a single Python application under music_assistant/ with tests/ beside it, and the dependency list in pyproject.toml tells you what the process carries. It pulls in aiohttp, aiosqlite, zeroconf, mutagen, pillow, librosa, numpy and torch. That mix points at the shape of the thing: an asyncio HTTP server, a local database, mDNS discovery for speakers on the network, tag and artwork reading for local files, and audio analysis for the heavier work.

Discovery is not an afterthought. zeroconf and aiohttp_asyncmdnsresolver are direct dependencies, so the server finds devices on the LAN rather than requiring you to type IP addresses. The Dockerfile goes further and bundles a separate cliairplay binary, downloaded per architecture with a checksum check, which tells you AirPlay support is handled by a binary shipped with the image rather than by Python code alone.

The frontend is not in this repository either. pyproject.toml pins music-assistant-frontend as a dependency, and music-assistant-models supplies the shared data models. The server is the core; the UI and the model definitions arrive as versioned packages.

Installing Music Assistant Server and reaching the UI

The README is direct about installation: the only officially supported ways to run the server are the Home Assistant app, which it recommends, and the Docker container ghcr.io/music-assistant/server. Both bundle the system dependencies. The server is not published to PyPI, and the README explains why: it needs a recent ffmpeg (6.1+) with a specific codec set, native libraries such as jemalloc and CIFS/NFS client libraries, and a few bundled binaries that a plain pip install cannot provide.

If you run Home Assistant, add the app repository and install from there. The README points at https://music-assistant.io/installation/ for the current steps, and the add-on repository URL is given in the README as a my.home-assistant.io redirect. For a Docker host, the image name is the whole story, and the README gives it as ghcr.io/music-assistant/server.

The README does not list the container's port mappings, volumes or environment variables, so take those from the documentation site rather than guessing. What you should see after a correct start is a reachable web UI served by the server process; the frontend package is a dependency, so the interface comes from the same install.

For development only, the repository documents a source route. You provide the system dependencies yourself, and the README states Python 3.14+ and ffmpeg 6.1+ are required. The README lists the scripts/setup.sh script, which creates the virtualenv and installs dependencies and pre-commit hooks. It also gives the command to run the server locally:

python -m music_assistant --log-level debug

According to the README, it listens on http://localhost:8095. The README also states that pytest runs the tests and that pre-commit run --all-files runs the linters. Treat this path as a development path, not a deployment one.

Where Music Assistant Server is the wrong tool

The clearest limitation is packaging. There is no PyPI release, and the README is explicit that there will not be one, because the server depends on OS-level components. If your deployment model is a virtualenv on a shared host, or a platform that only accepts Python packages, Music Assistant Server does not fit without you reproducing the ffmpeg build, the native libraries and the bundled binaries yourself.

The second constraint is the always-on requirement. The server is the core, and the README frames it as something that must run continuously. On a laptop that sleeps, discovery and playback will be unreliable in ways that look like bugs but are really the host going away.

The third is version drift. pyproject.toml pins a large set of dependencies at exact versions, including numpy==2.3.5 with a comment explaining that numpy 2.4.0 and later use an X86_V2 CPU baseline requiring SSE4.2, which breaks older CPUs. That is a deliberate ceiling, and it means an old low-power board can be a supported target while a newer dependency set is not.

Finally, the dependency list currently contains a git-pinned package, aiolibdatachannel, with a comment in pyproject.toml calling it a temporary test-drive pin to be replaced before merge. Anyone building from source on the dev branch inherits that.

How it compares to running a plain media server

The obvious alternative for a self-hoster is a general media server such as Jellyfin or Plex. The difference in approach is the direction of the data. Those tools are built around a library of files you own, indexed and served to clients, with streaming services treated as an add-on or not supported at all. Music Assistant Server is built around providers and players: the README describes it as connecting to your streaming services and a wide range of connected speakers, and the dependency list backs that up with mDNS discovery and a bundled AirPlay binary.

That means the two solve different problems. A file-based media server is the right answer if your collection is local and your clients are apps on phones and TVs. Music Assistant Server is the right answer if your sources are services and your endpoints are speakers scattered around a house, and especially if Home Assistant is already the thing issuing the commands. The README says the project is meant with automation in mind, and that framing is the real dividing line.

Licence, maintenance and the cost of upgrading

The repository is licensed Apache-2.0, stated both in the README and in pyproject.toml. That is a permissive licence, so redistributing the server or embedding it in a larger product is not the obstacle. The practical licence question sits elsewhere: the streaming services and the speaker firmware you connect to have their own terms, and nothing in this repository changes those. This is not legal advice.

On maintenance, the last push to the dev branch was on 2026-08-29, and the most recent releases listed are 2.11.0.dev2026082903 and 2.10.1, both dated 2026-08-29. The repository is not archived. The release naming shows two tracks running at once: a stable line and a nightly line built from dev.

The upgrade cost follows from the packaging. Because the server ships as a container or a Home Assistant app, an upgrade is a new image rather than a dependency resolution on your host, which keeps the ffmpeg and native library versions consistent with what the maintainers tested. The trade-off is that you inherit the pinned dependency set wholesale, including the numpy ceiling and the current git pin, and you cannot selectively upgrade a single library without leaving the supported path.

Editorial conclusion

Adopt Music Assistant Server if you already run Home Assistant or Docker on an always-on box and want one library over your streaming services and speakers; skip it if you want a pip-installable Python service or a desktop player. Before committing, confirm your host has ffmpeg 6.1+ and can run the ghcr.io/music-assistant/server image, and check the support tracker for your specific speaker and service.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes