Koel

Last reviewed Aug 26, 2026 · 851 words

Koel is the music server I show people to prove self-hosting does not have to look like 2009. The web player is genuinely lovely, smart playlists behave the way Spotify trained you to expect, and last.fm scrobbling is a checkbox. The trade is that Koel speaks only its own API. There is no Subsonic compatibility, so the whole ecosystem of third-party clients (Symfonium, DSub, play:Sub, Sonixd and the rest) is closed to you. You use Koel's web app and Koel's own mobile app, or you do not use Koel.

The interface is the product, and it earns its keep

Koel is a Laravel back end with a Vue front end, first released in 2016, MIT-licensed, and sitting at about 17,200 GitHub stars. What that stack buys you is a single-page player that feels native: keyboard shortcuts, drag-to-queue, an equaliser, album art fetched from Last.fm if you supply an API key, and a visualiser you will switch off after a day. Smart playlists are rule-based (genre is X, played fewer than 5 times, added in the last 30 days) and maintain themselves. Multi-user support is built in with per-user playlists and play counts, which makes it a sensible family server rather than a single-seat toy.

Budget a second container and 512 MB

The honest cost is the stack underneath. Koel is designed around MySQL, MariaDB or PostgreSQL, so you run 2 containers minimum, and it idles near the 512 MB the catalogue lists once the PHP workers are warm. The official image is phanan/koel:

services:
  koel:
    image: phanan/koel
    ports:
      - "8080:80"
    environment:
      - DB_CONNECTION=mysql
      - DB_HOST=db
      - DB_DATABASE=koel
      - DB_USERNAME=koel
      - DB_PASSWORD=change-me
    volumes:
      - /srv/music:/music:ro
      - ./covers:/var/www/html/public/img/covers
    restart: unless-stopped
  db:
    image: mariadb:11
    environment:
      - MARIADB_DATABASE=koel
      - MARIADB_USER=koel
      - MARIADB_PASSWORD=change-me
      - MARIADB_ROOT_PASSWORD=change-me-too
    volumes:
      - ./db:/var/lib/mysql
    restart: unless-stopped

First boot needs two commands inside the container: php artisan koel:init --no-assets to create the admin account and schema, then php artisan koel:scan (called koel:sync on older releases) to index /music. Mount the library read-only as above; Koel never needs to write to it, and a music server with write access to 400 GB of ripped CDs is a liability with no upside. Schedule the scan with cron or the built-in watcher rather than re-running it by hand.

Transcoding is one switch, not a subsystem

Koel plays files as-is. It can convert FLAC to MP3 on the fly with ffmpeg by setting TRANSCODE_FLAC=true and pointing FFMPEG_PATH at the binary, and that is close to the entire story. There is no bitrate ladder, no per-device profile, and no way to transcode anything that is not FLAC. If your collection is mostly lossless and you listen on cellular, flip the switch and accept the limits. If you want real transcoding control, Navidrome lets you set a format and bitrate per player, and Jellyfin does full media transcoding at the cost of being a much larger application.

The mobile story is Koel Player or the browser

Because there is no Subsonic API, your phone options are the responsive web app (fine on Wi-Fi, decent on mobile data) and Koel Player, the companion app for iOS and Android. It streams and handles playlists well; offline caching is its weak point. There is also Koel Plus, a paid one-time licence (about $50 at last check) that adds multiple libraries, cloud storage back ends such as S3 and Dropbox, and single sign-on. Most home users never need it, but it is how the project funds itself and the free tier is not crippled to sell it.

Koel against Navidrome, honestly

Navidrome is a single Go binary using SQLite, idles around 50 MB, scans faster, and speaks Subsonic so every third-party client works. Koel is prettier, needs 10 times the memory and an extra database, and locks you to its own clients. The Jellyfin vs Navidrome comparison covers the other common fork in the road; the wider media server category lists the rest. If you are leaving Spotify and your listening happens in a browser tab on a desk, Koel's interface is the thing you will notice every day. If it happens on a phone with a specific app you already like, Navidrome is the answer and Koel is not.

What I'd do

Run Koel if the web player is what sold you, because nothing else self-hosted looks this good. Pair it with MariaDB, mount the library read-only, set the FLAC switch if you have a lossless collection, and put the whole thing behind a reverse proxy with HTTPS so the mobile app works away from home. For a household that listens on phones through Symfonium or DSub, I would skip it and run Navidrome; the interface gap is real but the client ecosystem gap is bigger.