This is just a summary on how to get started. If you are stuck or have any questions, please join our Discord server and give us a shout on the
Using VSCode + Dev Container (Docker)
The project includes a VSCode Dev Container configuration for using with Docker. The Dev Container provides all dependencies out-of-the-box. If you prefer to install all dependencies yourself, or cannot/don’t want to install Docker for any reason, see the other sections below for step by step instructions for your OS.
NoteKeep in mind that the overall experience when using Docker Desktop for development will be slower than normal, because access to the host OS filesystem is generally slower. If you want to have full performance, we recommend installing the dependencies directly on your system and skip using Docker for development.
Unix-based systems (Linux, macOS, BSD, …)
Install GoLang 1.20+
Install Node 18
Install TagLib, preferable version 2.0
sudo apt install libtag1-dev
- Arch Linux:
pacman -S taglib
dnf install taglib-devel
brew install taglib --HEAD
- For other platforms check their installation instructions
Clone the project from https://github.com/navidrome/navidrome
Install development tools:
make setup. This may take a while to complete
make buildall. This command should create a
navidromeexecutable in the project’s folder
navidrome.tomlconfig file in the project’s folder with (at least) the following options:
# Set your music folder, preferable a specific development music library with few songs,
# to make scan fast
MusicFolder = "/path/to/music/folder"
# Make logging more verbose
LogLevel = "debug"
# This option will always create an `admin` user with the specified password, so you don't
# have to create a user every time you delete your dev database
DevAutoCreateAdminPassword = "password"
# Move the data/DB folder out of the root. `./data` folder is ignored by git
DataFolder = "./data"
# If you are developing in macOS with its firewall enabled, uncomment the next line to avoid
# having to accept incoming network connections every time the server restarts:
# Address = "localhost"
To start Navidrome in development mode, just run
make dev. This will start both the backend
and the frontend in “watch” mode, so any changes will automatically be reloaded. It will open
Navidrome automatically in your browser, using the URL http://localhost:4533/
If it does not open a new window in your browser, check the output for any error messages.
For more useful
make targets, run
Windows (using WSL)
Even though it is possible to setup a fully working Navidrome development environment in Windows, we currently don’t provide instructions for that (feel free to contribute to these docs if you successfully set it up).
- Make sure your Windows 10 is updated.
- Go to Settings > Turn Windows feature on or off > Windows subsystem for Linux.
- Go to Microsoft Store and download and install any Linux distro you like. For maximum compatibility, we recommend Ubuntu.
- Open Downloaded Linux distro, add username and password and then update it using:
sudo apt update && sudo apt upgrade -y.
- Install needed compilers for building Navidrome:
sudo apt install gcc g++
- This will create an Linux terminal where you can execute any Linux commands.
Make sure you are using WSL 2.0
Configuring Visual Studio Code
- Click on Extensions (present on leftmost column), install Remote Development extension and reload VSCode.
- Press F1, execute Remote-WSL: New Window. This will connect your installed Linux distro to VSCode.
- Now you can open a VSCode terminal and you’ll be able to run any Linux command.
- Because of this WSL issue you need to use your network IP address to be able to login to Navidrome in development mode. Otherwise you will get an
Error: Unauthorizedwhen logging in. You can see your network IP address after running
Now that you have a working instance of Linux running on your machine, follow the steps above for Unix-based system in the VSCode terminal. For more information on working with VSCode+WSL, check their documentation.
System limit for number of file watchers reached
If you encounter the
Error: ENOSPC: System limit for number of file watchers reached, watch while running
make dev on Linux systems, then your system is maxing out the number of files that can be “watched” for changes at one time.
To increase this limit, you can run the command
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p, which adds the line
/etc/sysctl.conf and reloads sysctl so the change takes effect. this allows
inotify to watch more files and folders for changes at a time.
More information about this can be found here
Was this page helpful?
Glad to hear it! Please tell us how we can make it even better.
Sorry to hear that. Please tell us how we can improve.