Koel (also styled as koel, with a lowercase k) is a web-based personal audio streaming service written in Vue at the client side and Laravel on the server side. Targeting web developers, Koel embraces some of the more modern web technologies to do its job.
Koel has two components, each with its own set of requirements:
- All requirements by Laravel – PHP, OpenSSL, and such. Consider setting PHP's
memory_limitto a good value (512M or better) if you have a big library.
- MySQL, MariaDB, PostgresSQL, or SQLite. Actually, any DBMS supported by Laravel should work.
- If you're building Koel from source, make sure to have Composer, Git, and NodeJS latest stable with
- Any evergreen browser will do – Koel has been tested on Chrome 47, Firefox 42, Safari 8, Opera 34, and Edge.
There are three methods to install and start using Koel:
# Using a Pre-Compiled Archive
Starting from v5.0.0, Koel supports installing from a pre-compiled archive, which eliminates the need of manually compiling the front-end assets.
First, go to the Releases page on GitHub, download either the
.zip file found under "Assets," and unzip it into the destination web root directory. From there, run the two following commands:
php artisan koel:init --no-assets # Populate necessary configurations during the process php artisan serve
# Building from Source
From your console, run the following commands:
cd <KOEL_ROOT_DIR> git clone https://github.com/koel/koel.git . git checkout latest # Check out the latest version at https://github.com/koel/koel/releases composer install php artisan koel:init # Populate necessary configurations during the process php artisan serve
In both cases, you should now be able to visit http://localhost:8000 in your browser and start using Koel.
Use a proper webserver
http://localhost:8000 is only the development server for Koel (or rather, Laravel). For optimal performance, you'll want to set up the production version, the configuration of which varies depending on your webserver of choice (Apache, nginx, Caddy etc.) and is outside of this document's scope, but shouldn't be any different from that of a standard PHP application.
If you want more control, edit
.env file. There's quite a few settings there to tweak Koel to your needs.
# Using Docker
Koel has an official Docker image: koel/docker.
Check out Releases for upgrade guides corresponding to your Koel version and installation method.
# Configuration and Usage
# Music Discovery
There are several ways for Koel to discover your media files. You can manually scan for songs, configure a watcher, host your files with Amazon S3, or upload files directly using the web interface.
# Scan using the web interface
Scanning via the web interface is vulnerably to HTTP timeout, so if you have a decent-sized library, opt for other methods instead.
Upload your songs into a readable directory on your server – preferably outside of your web root dir – and configure Koel to scan and sync it by setting a "media path" under Manage ▸ Settings.
# Scan using the CLI
You can also scan from the CLI – which is faster, without a time limit, and provides useful feedbacks – with the artisan
$ php artisan koel:sync INFO Scanning /Users/an/Personal/koel/media. 1189/1189 [============================] 100% INFO Scanning completed! ⇂ 0 new or updated song(s) ⇂ 1189 unchanged song(s) ⇂ 0 invalid file(s)
Suffix the command with a
-v flag for more details e.g. syncing errors.
This command can be added as a cron job, for example to run every midnight:
0 0 * * * cd /home/user/webapps/koel/ && /usr/local/bin/php artisan koel:sync >/dev/null 2>&1
As of current, Koel recognizes these audio extensions:
.flac (experimental with some limitations). Others may be added in the future.
# Upload using the web interface
Starting from v4.3.0, you can upload songs directly as an admin by clicking the "Upload" sidebar menu item. Note that you need to set the media path first, as songs will be uploaded into the
Depending on how big your files are, you may want to set
post_max_size in your
php.ini correspondingly, or uploading may fail with a
Payload too large error.
# Watch a directory
Starting from v2.1.0, you can watch a directory and sync on the fly with
# Host your media on Amazon S3
Starting from v3.0.0, you can use Koel with Amazon S3.
# Streaming Music
Koel supports three streaming methods which can be configured via a
STREAMING_METHOD setting in
php: Use native PHP
readfile(). This is the default method, and the slowest and most unstable one. Only use this method if you can't others.
x-sendfile: Use Apache's mod_xsendfile module. You'll need to install and configure the module manually. A sample configuration is as following:
LoadModule xsendfile_module libexec/apache2/mod_xsendfile.so # These configuration can be put in the VirtualHost directive as well <IfModule mod_xsendfile.c> XSendFile on XSendFilePath /mnt/media </IfModule>
If you're using a Koel mobile app and can't play the songs, try switching the streaming method to
x-sendfile instead of
STREAMING_METHOD doesn't have effects if you're transcoding or serving songs from Amazon S3.
# Using the Web Interface
Using the client component of Koel should be straightforward enough. If you've ever used Spotify, you should feel right at home. As a matter of fact, Koel's client interface is a shameless rip-off of Spotify's. You can search, you can sort, you can view by artists or albums, you can create playlists, you can like/unlike songs, and you can create other users to share the vibes. There are a couple of shortcut keys, too, for the nerds:
- F puts the focus into the search box
- Enter plays a song. If multiple songs are being selected, Enter adds them to the bottom of the queue, Shift+Enter queues them to top. Adding a Cmd or Ctrl into the combo plays the first selected song right away.
- Space toggles playback
- J plays the next song in queue
- K plays the previous song in queue
- Ctrl/Cmd+A selects all songs in the current view
- Delete removes selected song(s) from the current queue/playlist
With a browser that supports MediaSession, you can control Koel using hardware media keys without even having Koel or the browser focused.
# Instant Search
Starting from v5.0.0, Koel provides an instant search feature that performs full-text, fuzzy searches against your database of songs, albums, and artists. By default, Koel uses the TNTSearch engine, which requires no configuration. You can also use Algolia by populating these details into
SCOUT_DRIVER=algolia ALGOLIA_APP_ID=<your-algolia-app-id> ALGOLIA_SECRET=<your-algolia-secret>
Similarly, you can use Meilisearch with these configurations:
SCOUT_DRIVER=meilisearch MEILISEARCH_HOST=<your-meilisearch-host> MEILISEARCH_KEY=<your-meilisearch-key>
If you're upgrading Koel from an older version, you'll also have to create the search indices manually by running this command:
php artisan koel:search:import
All subsequent updates to the music database will be synchronized automatically.
Koel supports multiple themes. You can preview and choose one from from the Profile & Preferences screen. Note that themes are not persisted across devices, as they make use of the browser's local storage.
# Upload Artist and Album Images
You can change the artist and album images by dragging and dropping images into the current images in artist/album cards.
# User Management
Koel supports multiple users. A user can be an admin who has administrative privileges (user and media management) or a standard one. As of current, all users share the same library (though playlists, favorites, and other stats are private). Full multi-tenant support may be considered in the future.
# Remote Controller
Starting from v3.7.0, Koel has a (mobile) remote controller that lets you control a desktop instance – play/pause, navigate, turn volume up/down, and add/remove from Favorites.
In order to use the feature:
- Register a Pusher account and create an app
- Populate the app's credentials into
.env(those start with
- Reload the desktop Koel instance
- Go to http://<your-koel-host>/remote on a mobile device to start controlling remotely. You may also want to add the URL to the home screen for faster access later.
# Reset Admin Password
Starting from v4.1.1, Koel comes with a handy CLI command to reset the admin password in case you lose it:
php artisan koel:admin:change-password
For older versions, you can make use of Laravel's Tinker, as described here.
# Mobile Support and Limitation
Koel's fully responsive GUI works fairly well on a mobile device. Certain functionalities are not available (yet), however:
- Shortcut keys don't work (duh)
- Volume can only be controlled from a system level
- Next and previous songs can't be controlled from Control Center or lock screen
Also, since Safari is the new IE, if you're on iOS, it's strongly advised to use Koel with a non-Safari browser such as Firefox, Microsoft Edge, Brave, or Google Chrome. iOS 14 comes with the ability to change the default browser as well.
For a better mobile experience, it's strongly recommended to use one of the official mobile apps instead.
# Local Development
# Running the Local Webserver
$ yarn dev vite v2.9.13 dev server running at: > Local: http://localhost:3000/ > Network: use `--host` to expose ready in 761ms. Laravel v9.22.1 > APP_URL: http://localhost
A development version of Koel should now be available at
http://localhost:8000 with full HMR support.
# 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
# Sponsors and Support
The continuous development of Koel is made possible thanks to the support from these generous sponsors: