Need help with koel?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

12.9K Stars 1.7K Forks MIT License 2.0K Commits 71 Opened issues


🐦 A personal music streaming server that works.

Services available


Need anything else?

Contributors list

koel e2e unit Code Quality codecov OpenCollective OpenCollective



Koel (also stylized as koel, with a lowercase k) is a simple web-based personal audio streaming service written in Vue on the client side and Laravel on the server side. Targeting web developers, Koel embraces some of the more modern web technologies – CSS grid, audio, and drag-and-drop API to name a few – to do its job.

Install and Upgrade Guide

For system requirements, installation/upgrade guides, troubleshooting etc., head over to the Official Documentation.


Since Koel makes use of git submodules, you'll want to make sure the submodule is up-to-date:

git pull
git submodule update --init --recursive --remote

install the submodule dependencies

cd resources/assets yarn install

To start the PHP dev server, which serves as the API of the application, run the following command from the root directory. By default, the server will listen at port

php artisan serve

For the client application itself, run this command:

yarn hot

A development version of Koel should now be available at

with full support for hot module reloading.

Alternatively, you can start both the PHP server and the client application in one go with

yarn dev
, which uses
under the hood.

Testing, Linting, Static Analysis and Stuff

# PHP-related code quality tasks
# Basically, take a look at the "scripts" section in composer.json
composer test        # Run the PHP test suite
composer cs          # Run code style checker
composer cs:fix      # Run code style fixer 
composer analyze     # Run PHP static analysis

yarn build # Build a production version of the client application

Client/E2E code quality tasks

You may want to run yarn build first.

yarn test:e2e # Run the Cypress test suite interactively yarn test:e2e:ci # Run the Cypress test suite non-interactively (CI mode)

These commands need to be run from within the submodule (resources/assets)

yarn lint # Lint yarn type-check # TypeScript type checking yarn test # Unit testing

Note: If you're already running

yarn test:e2e
, there's no need to start a dev server.
yarn test:e2e
yarn dev
internally and will eliminate the existing
yarn dev
process, if any.

A quick and easy way to start hacking on koel is to open and run this repo in Gitpod, an online IDE with full Laravel support.

Open in Gitpod

Koel Player

Koel Player screenshots

Koel Player is the official mobile app for Koel, which supports both iOS and Android without the limitations of the mobile web version. For more information on the project, visit its repository.


Support me on OpenCollective with a monthly donation and help me continue building Koel.


GitHub Sponsors


Become a sponsor on OpenCollective and get your logo on our README on Github with a link to your site.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.