Skip to content
Get packs

Guide · Open source

How to use koel: install, stream your music and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

Koel is a free, open-source music streaming app that scans your personal music collection and plays it through a web-based player that works in any browser. This guide explains what Koel does, how to get the code, where to find full setup instructions, and how to decide whether it fits your library. After reading, you will know which parts of Koel are covered by the project's README and where to go for the rest.

Koelkoel/koel · ★ 17.3k · MIT

Quick start

  1. 1Confirm you want self-hosting. Koel is a self-hosted app. Check that you are comfortable running your own server before you start.
  2. 2Clone the repository. Run the README's git clone command to download the koel source code from GitHub.
  3. 3Read the official documentation. Open docs.koel.dev and follow its installation guide and system requirements for your setup.
  4. 4Point Koel at your music library. Follow the documentation to set up the scan of your personal music collection so Koel can index it.
  5. 5Open the web player. Load Koel in your browser to play your library, then build playlists and try radio or podcasts.
  6. 6Add optional integrations. Connect Last.fm, Spotify or MusicBrainz if you want scrobbling or metadata, using the setup steps in the documentation.

What Koel does

Koel scans your music library and serves it back through a fast, modern interface that works in any browser. It is built on Laravel and Vue.

Beyond basic playback, the README lists playlists, smart playlists, scrobbling, podcasts, radio, Last.fm, Spotify and MusicBrainz integrations, and an AI assistant that responds to natural-language commands.

  • Playback of your own music library in a browser
  • Playlists and smart playlists
  • Scrobbling and Last.fm, Spotify and MusicBrainz integrations
  • Podcasts and radio
  • An AI assistant that takes natural-language commands

Get the Koel source code

The README's install command clones the repository from GitHub. Run it in the folder where you want the project to live.

The README does not list prerequisites, so check the official documentation for what your server needs before you continue.

git clone https://github.com/koel/koel.git

Where to find installation and upgrade instructions

The README sends installation, upgrade, system requirements and troubleshooting questions to the Official Documentation at docs.koel.dev. Use that site as the source of truth for setup steps, because the README itself does not walk through them.

If you plan to change the code, the README points to a separate Development Guide at docs.koel.dev/development.

  • Installation and upgrade guides: docs.koel.dev
  • System requirements: docs.koel.dev
  • Development guide: docs.koel.dev/development

Know the limits of the free edition

The README describes Koel Plus as a separate premium edition. It adds multi-user libraries, collaboration, SSO, cloud storage drivers, custom themes and white-labeling.

If you need any of those features, plan for Koel Plus or another tool. The free project does not include them according to the README.

  • Multi-user libraries (Koel Plus)
  • Collaboration (Koel Plus)
  • SSO (Koel Plus)
  • Cloud storage drivers (Koel Plus)

Listen on mobile with Koel Player

The README says the official mobile app is a separate project called Koel Player, which supports iOS and Android without the limitations of the mobile web version. Install it from its own repository rather than expecting the main project to provide a native app.

What people use it for

  • Listening to a personal music library from any browser on your home network
  • Keeping playlists, smart playlists and scrobbling in one self-hosted place
  • Browsing and playing podcasts and radio alongside your own music
  • Reading or extending a Laravel and Vue codebase as a developer

Frequently asked questions

Is Koel free?

Koel is free and open source under the MIT licence, according to the README. The README describes Koel Plus as a separate premium edition with extra features.

What license does Koel use?

Koel uses the MIT licence. The MIT licence allows you to use, modify and redistribute the code, subject to its terms.

How do I install Koel?

The README gives a git clone command to download the source code. For full installation steps and system requirements, the README points to the official documentation at docs.koel.dev.

Does Koel have a mobile app?

The README says the official mobile app is a separate project called Koel Player, which supports iOS and Android. It is not part of the main Koel repository.

Is Koel a good alternative to Navidrome, Jellyfin or Airsonic?

Navidrome, Jellyfin and Airsonic are comparable self-hosted projects. Koel stands out for its built-in playlists, scrobbling, radio and AI assistant, but this guide does not benchmark them, so compare features against your own needs.

Does Koel support multiple users or cloud storage?

The README says multi-user libraries, SSO and cloud storage drivers are part of the premium Koel Plus edition, not the free project. Check the documentation for current details.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Koel suits people who want to listen to their own music in a browser and are comfortable running a self-hosted server. It is less suited to anyone who wants a hosted service with no setup, a native mobile app from the main project, or multi-user and cloud storage features without the paid Koel Plus edition.

Install options & downloads