Funkwhale

Last reviewed Sep 13, 2026 · 858 words

Most people who land on Funkwhale want Navidrome and do not know it yet. If the goal is "my FLAC collection on my phone", Navidrome does that with one Go binary and about 100 MB of RAM. Funkwhale is for a different goal: a music server that is also a small social network, where other instances can follow your library, a local band can publish an album as a channel, and a community can pool a shared collection. That is a real niche, 2,700 stars deep, and it costs you PostgreSQL, Redis, a Celery worker, and a Hard difficulty rating to get there.

Federation is the feature and also the setup cost

Funkwhale speaks ActivityPub, the same protocol as Mastodon. Your instance, which the project calls a pod, exposes libraries that users on other pods can follow; artists publish channels that show up in fediverse timelines. In practice, federated library sharing between two small friend-run pods is where I have seen it earn its keep: each side keeps its own collection, follows the other, and streams what the other has without duplicating the files.

The price is a Django application with real moving parts. The official compose stack runs six services: postgres, redis, api, celeryworker, celerybeat, and an nginx front. Nothing about that is exotic, but it is not a single container you forget about, and the 1 GB minimum in the catalogue is honest rather than padded. Upgrades involve database migrations, and the project lives on its own GitLab at dev.funkwhale.audio, so if you only search GitHub you will miss it entirely.

The compose stack, and the import command you need

Grab the upstream docker-compose.yml and .env from the docs at docs.funkwhale.audio rather than hand-writing them; the .env is where the decisions live:

FUNKWHALE_HOSTNAME=music.example.com
FUNKWHALE_PROTOCOL=https
DJANGO_SECRET_KEY=$(openssl rand -hex 32)
MUSIC_DIRECTORY_PATH=/music
MUSIC_DIRECTORY_SERVE_PATH=/srv/music
MEDIA_ROOT=/srv/funkwhale/data/media

Put Caddy or Traefik in front for TLS; federation refuses to work over plain HTTP, and the web player is unhappy about it too. Then the part that trips everyone: Funkwhale does not scan a folder on its own. You create a library in the web UI, copy its ID, and import in place so files are referenced rather than copied:

docker compose run --rm api funkwhale-manage import_files \
  <library-id> "/music/" --recursive --noinput --in-place

Skip --in-place and Funkwhale duplicates your collection into MEDIA_ROOT, which is how people end up with a 400 GB volume they did not plan for. Tag quality matters more here than in Navidrome, because MusicBrainz IDs drive artist and album grouping and the UI has no "just show me the folder" fallback.

Subsonic compatibility gets you proper mobile apps

Funkwhale's own web player is fine on a laptop and mediocre on a phone. What saves it is a Subsonic-compatible API, switched on per user in settings, which means Symfonium, Ultrasonic, DSub, and play:Sub all work against it the same way they work against Navidrome or Gonic. Offline caching, gapless playback, and Android Auto come from those apps, not from Funkwhale. If you were going to judge Funkwhale on its bundled player, don't; judge it on how it behaves behind a client you already like.

Podcasts and channels are the underrated half

Channels are Funkwhale's publishing side: an artist or a podcaster gets an RSS feed and an ActivityPub actor from one upload flow, with no separate hosting. For the listening side, Funkwhale subscribes to ordinary podcast RSS feeds and exposes them in the same library. It is not as polished a podcast client as Audiobookshelf, which has better progress sync and a proper mobile app, but for a community that wants to publish a show and host the archive on the same box, having both halves in one service is genuinely convenient.

Who actually runs it

Three groups, in my experience. Small collectives and netlabels that want to publish under their own domain and be followable from Mastodon. Friend groups with two or three pods sharing libraries. And people already deep in the fediverse who want their music server to be a citizen of it. If you are none of those, you are paying the complexity tax for features you will not touch, and the bigger project in the media server category is the safer bet. The Navidrome walkthrough covers that path in detail.

What I'd do

Run Navidrome unless the word "federation" made you sit up. If it did, deploy the official compose stack on a box with 2 GB free, put it behind Caddy with a real hostname on day one, import your collection with --in-place, and turn on the Subsonic API before you judge the listening experience. Back up the PostgreSQL database and MEDIA_ROOT together; one without the other restores to a broken instance. Budget an afternoon for the first setup and an hour per major upgrade, and expect the AGPL-3.0 licence to be irrelevant unless you plan to sell access.