Development Environment

Any IDE with good support for GoLang and JavaScript/Node can be used for Navidrome development. We suggest using Visual Studio Code, which has excellent support for both languages.

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.

Unix-based systems (Linux, macOS, BSD, …)

1. Install GoLang 1.22+

2. Install Node 20

3. Install TagLib, preferable version 2.0

   • Ubuntu: sudo apt install libtag1-dev
   • Arch Linux: pacman -S taglib
   • Fedora: dnf install taglib-devel
   • macOS: brew install taglib --HEAD
   • For other platforms check their installation instructions

4. Install pkg-config

5. Clone the project from https://github.com/navidrome/navidrome

6. Install development tools: make setup. This may take a while to complete

7. Test installation: make buildall. This command should create a navidrome executable in the project’s folder

8. Create a navidrome.toml config 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 make help.

Building it locally

To build Navidrome locally, follow these steps:

1. Make sure you have all the dependencies installed as mentioned in the previous sections.
2. Open a terminal and navigate to the project’s folder.
3. Run the command make buildjs to build the frontend assets. This will build the Web UI in the ui/build folder
4. Run the command make build to build the backend server. This will create a navidrome binary in the project’s folder

Alternatively, you can call make buildall to build both backend and frontend. Not very useful if you are only changing one of them.

Building with Docker

If you want to build Navidrome for a different platform than your own dev environment, use make single and specify the OS/Platform as parameters. Example for Linux/ARM:

make single GOOS=linux GOARCH=arm

If you want to build a Docker image with your local changes, use make docker. Note that this command only build images for linux/amd64. The built image will be tagged locally as deluan/navidrome:develop

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).

The (arguably better) alternative is to set up the project using Visual Studio Code and WSL, which effectively lets you develop in a Linux environment while still using your Windows system.

Installing WSL

1. Make sure your Windows 10 is updated.
2. Go to Settings > Turn Windows feature on or off > Windows subsystem for Linux.
3. Go to Microsoft Store and download and install any Linux distro you like. For maximum compatibility, we recommend Ubuntu.
4. Open Downloaded Linux distro, add username and password and then update it using: sudo apt update && sudo apt upgrade -y.
5. Install needed compilers for building Navidrome: sudo apt install gcc g++
6. 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

1. Click on Extensions (present on leftmost column), install Remote Development extension and reload VSCode.
2. Press F1, execute Remote-WSL: New Window. This will connect your installed Linux distro to VSCode.
3. Now you can open a VSCode terminal and you’ll be able to run any Linux command.

Common Issues

1. 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: Unauthorized when logging in. You can see your network IP address after running make dev.

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.

Troubleshooting

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 fs.inotify.max_user_watches=524288 to /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