Installation

• 1: Windows Install
• 2: Installing with Docker
• 3: Linux Install
• 4: macOS Install
• 5: FreeBSD Install
• 6: Community Maintained Packages
• 7: Managed Hosting
• 8: Build from sources

1 - Windows Install

MSI Install

Download and install the latest Navidrome MSI for the correct version of Windows (most likely AMD64). The installer will prompt for basic configuration options (port, directories etc). These can be left as default or customised to your setup. The service will be installed and started automatically, once the installer has completed you can go to [http://127.0.0.1:4533] (or whichever port you chose) in a browser and setup the first user. The navidrome.ini configuration file will be located in the installation folder (default: C:\Program Files\Navidrome).

Further modification can be made by changing the navidrome.ini file after installation and restarting the service.

Manual Installation

Since Navidrome needs to be run from the command line, it is suggested to use a service wrapper to make it into a service as it does not make sense to have a terminal window open whenever you want to use Navidrome. The examples below are for Shawl, NSSM and WinSW.

Using Shawl

Prebuilt binaries are available on the releases page of Shawl. It’s portable, so you can simply download it and put it anywhere without going through an installer. Otherwise if you have Rust installed, you can run cargo install shawl.

Here’s how you create the service with Shawl, then start it. Note that this has to be run from an administrator command prompt.

shawl add --name Navidrome -- "C:\Services\navidrome\navidrome.exe" -c "C:\Services\navidrome\navidrome.toml"
sc start Navidrome

Using NSSM

No installation is required for NSSM. Just grab the latest release from their download page and install the Navidrome service from an administrator command prompt using NSSM:

nssm install Navidrome

This opens a window where you can set the properties of the service; most notably, the path to the executable, the user account on which to run the service, the output files (stout and sterr) and file rotation. More information about the configurable options can be found here.

You can also bypass the GUI and install the service from the command line only. Below is an example:

nssm install Navidrome "C:\Services\navidrome\navidrome.exe"
nssm set Navidrome AppDirectory "C:\Services\navidrome\"
nssm set Navidrome DisplayName Navidrome
# The username and password of the user account under which the service will run.
nssm set Navidrome ObjectName "username" "password"
nssm set Navidrome AppStdout "C:\Services\navidrome\navidrome.log"
nssm set Navidrome AppStderr "C:\Services\navidrome\navidrome.log"
nssm set Navidrome AppRotateFiles 1
nssm set Navidrome AppRotateSeconds 86400
nssm set Navidrome AppRotateBytes 10240

# Start the service
sc start Navidrome

Using WinSW

To use WinSW, download the WinSW binary from their download page. WinSW also requires a configuration file (more details about the WinSW configuration file here) to be able to manage an application.

A basic example (where both Navidrome and the WinSW configuration file are in the same directory) for Navidrome is down below:

<service>
  <id>Navidrome</id>
  <name>Navidrome</name>
  <description>Modern Music Server and Streamer compatible with Subsonic/Airsonic</description>
  <executable>C:\Services\navidrome\navidrome.exe</executable>
  <arguments>-c navidrome.toml</arguments>
  <log mode="roll-by-size"></log>
</service>

Save this in a file named navidrome.xml. Then, run these commands from an administrator command prompt to install the service, start it and check its status:

winsw install navidrome.xml
winsw start navidrome.xml
winsw status navidrome.xml

Verify that the service has started as expected by navigating to http://localhost:4533, by checking the Services Management Console or by checking the log file that the service wrapper created.

2 - Installing with Docker

Docker images are available for the linux/amd64, linux/arm/v6, linux/arm/v7 and linux/arm64 platforms. They include everything needed to run Navidrome.

Using docker-compose :

Create a docker-compose.yml file with the following content (or add the navidrome service below to your existing file):

services:
  navidrome:
    image: deluan/navidrome:latest
    user: 1000:1000 # should be owner of volumes
    ports:
      - "4533:4533"
    restart: unless-stopped
    environment:
      # Optional: put your config options customization here. Examples:
      # ND_LOGLEVEL: debug
    volumes:
      - "/path/to/data:/data"
      - "/path/to/your/music/folder:/music:ro"

Start it with docker-compose up -d. Note that the environment variables above are just an example and are not required. The values in the example are already the defaults

Using docker command line tool:

$ docker run -d \
   --name navidrome \
   --restart=unless-stopped \
   --user $(id -u):$(id -g) \
   -v /path/to/music:/music \
   -v /path/to/data:/data \
   -p 4533:4533 \
   -e ND_LOGLEVEL=info \
   deluan/navidrome:latest

Customization

• The user argument should ideally reflect the UID:GID of the owner of the music library to avoid permission issues. For testing purpose you could omit this directive, but as a rule of thumb you should not run a production container as root.
• Remember to change the volumes paths to point to your local paths. /data is where Navidrome will store its DB and cache, /music is where your music files are stored.
• Configuration options can be customized with environment variables as needed. For docker-compose just add them to the environment section or the yml file. For docker cli use the -e parameter. Ex: -e ND_SESSIONTIMEOUT=24h.
• If you want to use a configuration file with Navidrome running in Docker, you can create a navidrome.toml config file in the /data folder and set the option ND_CONFIGFILE=/data/navidrome.toml.

3 - Linux Install

Install Navidrome Using Pre-built Binary

To install Navidrome on a Linux system using a .deb file, you can follow a streamlined process that leverages the convenience of Debian package management. This method simplifies the installation by eliminating the need to manually download and extract binaries.

Before you begin, ensure that your system is up to date and that you have ffmpeg installed, as it is a requirement for Navidrome to function properly.

sudo apt update
sudo apt upgrade

Download the .deb File

1. Visit the Navidrome Releases Page: Go to the Navidrome releases page on GitHub to find the latest .deb package suitable for your system architecture (e.g., amd64 for 64-bit systems).

2. Download the .deb File: Use wget or your browser to download the .deb file. Replace navidrome_0.XX.X_amd64.deb with the actual file name from the releases page.

wget https://github.com/navidrome/navidrome/releases/download/v0.XX.X/navidrome_0.XX.X_amd64.deb

Install and Configure

There are two ways to install the package, apt and dpkg. apt is the usual method because it will automatically determine dependancies and install them (ffmpeg).

Using apt:

sudo apt install ./navidrome_0.XX.X_linux_amd64.deb

Using dpkg:

Install the package and then resolve the dependancies:

sudo dpkg -i ./navidrome_0.XX.X_amd64.deb
sudo apt install -f

Configuration File: After installation, Navidrome MUST be configured to run. The default path for the configuration file is /etc/navidrome/navidrome.toml. Create and edit the file using nano directly.

sudo nano /etc/navidrome/navidrome.toml

Add/update the following line to specify your music library path:

MusicFolder = "/path/to/your/music/library"

If the MusicFolder is not set, that the default music path is /opt/navidrome/music and it will be running as user navidrome.

For additional configuration options see the configuration options page.

Start the Navidrome Service: Use systemctl to start the Navidrome service and set it to run on startup.

sudo systemctl enable --now navidrome

Check Service Status: Verify that Navidrome is running correctly.

sudo systemctl status navidrome
sudo journalctl -u navidrome -f

If everything is set up correctly, Navidrome will be accessible via web browser: http://localhost:4533.

Migrate from manual installation to .deb Pre-built package

Migrating from a manually installed Navidrome instance to the new pre-built .deb package version can streamline updates and maintenance. This guide will walk you through the process of migrating your existing Navidrome setup on Linux to the .deb package version, specifically from the 0.54.1 release.

Before starting the migration, ensure you have:

• Backup: Always back up your current Navidrome configuration and music library. This includes the navidrome.toml configuration file and any other custom settings you may have.
• System Update: Make sure your system is up to date.

sudo apt update
sudo apt upgrade

Remove Existing Program

First, stop the currently running Navidrome service to prevent any conflicts during the installation of the new package.

sudo systemctl stop navidrome.service

Navigate to the directory where your self-built Navidrome is located and remove the files. Be cautious not to delete your configuration or music library.

sudo rm -rf /opt/navidrome

Installation

The machine is now clean and ready for installation. Follow the regular Linux installation instructions above. Just be sure to place the config file and database in appropriate locations (/etc/navidrome/navidrome.toml).

Additional Considerations

• Permissions: Ensure that the user navidrone which is used by the program has the necessary permissions to access your music library.
• Environment Variables: If you had any custom environment variables set in your previous setup, make sure to configure them in the new setup as well.

Manual installation on Linux

Navidrome can also be installed using a self-built binary. In order to do so, first ensure your system is up to date and install ffmpeg.

sudo apt update
sudo apt upgrade
sudo apt install vim ffmpeg

Create Directory Structure

Create a directory to store the Navidrome executable and a working directory with the proper permissions.

sudo install -d -o <user> -g <group> /opt/navidrome
sudo install -d -o <user> -g <group> /var/lib/navidrome

Get Navidrome

Download the latest release from the releases page, extract the contents to the executable directory, and set the permissions for the files. (Replace the URL below with the one from the releases page):

wget https://github.com/navidrome/navidrome/releases/download/v0.XX.X/navidrome_0.XX.X_linux_amd64.tar.gz -O Navidrome.tar.gz
sudo tar -xvzf Navidrome.tar.gz -C /opt/navidrome/
sudo chmod +x /opt/navidrome/navidrome
sudo chown -R <user>:<group> /opt/navidrome

Create Configuration File

In the directory /etc/navidrome create a new file named navidrome.toml with the following settings.

MusicFolder = "<library_path>"

For additional configuration options see the configuration options page.

Create a systemd Unit

Create a new file under /etc/systemd/system/ named navidrome.service with the following data. Make sure you replace <user> and <group> with the user and group you want to run Navidrome under. If you use the backup feature, you will also need to add the backup path to the systemd allow-list for Navidrome as shown in the Backup usage documentation.

[Unit]
Description=Navidrome Music Server and Streamer compatible with Subsonic/Airsonic
After=remote-fs.target network.target
AssertPathExists=/var/lib/navidrome

[Install]
WantedBy=multi-user.target

[Service]
User=<user>
Group=<group>
Type=simple
ExecStart=/opt/navidrome/navidrome --configfile "/etc/navidrome/navidrome.toml"
WorkingDirectory=/var/lib/navidrome
TimeoutStopSec=20
KillMode=process
Restart=on-failure

# See https://www.freedesktop.org/software/systemd/man/systemd.exec.html
DevicePolicy=closed
NoNewPrivileges=yes
PrivateTmp=yes
PrivateUsers=yes
ProtectControlGroups=yes
ProtectKernelModules=yes
ProtectKernelTunables=yes
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
RestrictNamespaces=yes
RestrictRealtime=yes
SystemCallFilter=~@clock @debug @module @mount @obsolete @reboot @setuid @swap
ReadWritePaths=/var/lib/navidrome

# You can uncomment the following line if you're not using the jukebox This
# will prevent navidrome from accessing any real (physical) devices
#PrivateDevices=yes

# You can change the following line to `strict` instead of `full` if you don't
# want navidrome to be able to write anything on your filesystem outside of
# /var/lib/navidrome.
ProtectSystem=full

# You can uncomment the following line if you don't have any media in /home/*.
# This will prevent navidrome from ever reading/writing anything there.
#ProtectHome=true

# You can customize some Navidrome config options by setting environment variables here. Ex:
#Environment=ND_BASEURL="/navidrome"

Start the Navidrome Service

Reload the service daemon, start the newly create service, and verify it has started correctly.

sudo systemctl daemon-reload
sudo systemctl start navidrome.service
sudo systemctl status navidrome.service

If the service has started correctly verify you can access http://localhost:4533.

Start Navidrome on Startup

sudo systemctl enable navidrome.service

4 - macOS Install

Navidrome can be ran by simply double-clicking the binary that has been downloaded from the release page or by running it in the command line. However, that will keep a terminal window open while Navidrome is running.

To have Navidrome running in the background, we can run it as a service. We define a service as shown below and save that in a file named navidrome.plist in the ~/Library/LaunchAgents/ folder.

The example shown assumes a few things:

1. The binary has been downloaded and extracted to the /opt/navidrome folder.
2. A configuration file for Navidrome has been created and is named navidrome.toml in that folder. Be sure to set the DataFolder option as well.
3. A log file for Navidrome has been created and is named navidrome.log in that folder.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>navidrome</string>
        <key>ProgramArguments</key>
        <array>
            <string>/opt/navidrome/navidrome</string>
            <string>-c</string>
            <string>/opt/navidrome/navidrome.toml</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>StandardOutPath</key>
        <string>/opt/navidrome/navidrome.log</string>
        <key>StandardErrorPath</key>
        <string>/opt/navidrome/navidrome.log</string>
    </dict>
</plist>

Then to load the service, run:

launchctl load ~/Library/LaunchAgents/navidrome.plist

To start the service, run:

launchctl start navidrome

You can verify that Navidrome has started by navigating to http://localhost:4533, by running launchctl list | grep navidrome or by checking the log file specified.

To stop the service, run:

launchctl stop navidrome

5 - FreeBSD Install

The following steps have been tested on FreeBSD 12 and 13. They should work on all versions 11.4 and above as well as other supported versions. All prerequisites will be automatically installed when using a package or if building from ports. Throughout these instructions the commands will have placeholders for the user (<user>) and group (<group>) you want to run Navidrome under and the music folder path (<library_path>). If you are using an existing media library ensure the user has permissions to the media library.

Install Using Package

Use the package tool (pkg) to install Navidrome from a binary package.

pkg install navidrome

Follow any on screen instructions to complete your installation.

Build & Install Using Ports

Instead of using a binary package you can build from source. Before you start, make sure your local ports tree is up to date. Refer to the FreeBSD Handbook on the recommended way to fetch or update your ports tree.

Switch to the port directory for Navidrome and run make install.

cd /usr/ports/multimedia/navidrome
make install

The build process could take several minutes depending on the speed of your computer. Follow any on screen instructions to complete your installation.

Start the Navidrome Service

Start the service and verify it has started correctly.

service navidrome onestart
service navidrome onestatus

Navidrome is configured to listen on 127.0.0.1 on port 4533. The <library_path> is preset to ${PREFIX}/share/navidrome/music If the service has started correctly, verify you can access http://localhost:4533.

To run Navidrome at system startup, enable the service in /etc/rc.conf:

sysrc navidrome_enable="YES"

Customizing your Installation

The defaults provided out of the box by the port and package are sufficient to get your started. You can customize these settings if required by using a combonation of /etc/rc.conf and the Navidrome configuration file.

Run as a Different User

Navidrome will run as the www user. If you need to change it to something else use /etc/rc.conf to set a user and group. You can easily adjust this using the sysrc tool:

sysrc navidrome_user="<user>"
sysrc navidrome_group="<group>"

Configuration File Location

A default configuration file will be installed under /usr/local/etc/navidrome named config.toml. This can be changed by setting a new path in /etc/rc.conf. You can easily adjust this using the sysrc tool:

sysrc navidrome_config="/path/to/new/config_file.toml"

Make sure the user Navidrome is running as has permission to read the file.

For additional configuration options see the configuration options page.

Data Folder

The data folder is located under /var/db/navidrome. The prefered way to change this is by using /etc/rc.conf You can easily adjust this using the sysrc tool:

sysrc navidrome_datafolder="/path/to/new/folder"

Make sure the user Navidrome is running as has permission to read and write to the folder contents.

6 - Community Maintained Packages

Even though the Navidrome project does not provide any pre-packaged installation for specific platforms, there are some packages created and maintained by the community, that can simplify the setup on some systems.

Here is the list of packages for various OSes/Distributions, provided by Repology:

More packages available, with links to download/install instructions:

If you create, or know of, other Navidrome packages that are publicly available, please add to the list above.

7 - Managed Hosting

The following providers offer managed hosting for Navidrome. This can be a good option if you don’t want to manage your own server.

PikaPods

Offers 1-click deployments for Navidrome with $5 free welcome credit. EU and US regions available. Includes daily backups and regular app updates.

8 - Build from sources

If you can’t find a pre-built binary for your platform, you should open an issue in the project’s GitHub page.

If you don’t want to wait, you can try to build the binary yourself, with the following steps.

First, you will need to install Go 1.22+ and Node 20+. The setup is very strict, and the steps below only work with these versions (enforced in the Makefile). Make sure to add $GOPATH/bin to your PATH as described in the official Go site

You’ll also need to install the TagLib library:

• Debian/Ubuntu: sudo apt install libtag1-dev
• Arch Linux: pacman -S taglib
• macOS: brew install taglib
• FreeBSD: pkg install taglib
• For other platforms check their installation instructions

After the prerequisites above are installed, clone Navidrome’s repository and build it:

$ git clone https://github.com/navidrome/navidrome
$ cd navidrome
$ make setup        # Install build dependencies
$ make build        # Build UI and server, generates a single executable

On FreeBSD you have to use gmake:

$ git clone https://github.com/navidrome/navidrome
$ cd navidrome
$ gmake setup        # Install build dependencies
$ gmake build        # Build UI and server, generates a single executable

This will generate the navidrome executable binary in the project’s root folder.

NOTE: Remember to install ffmpeg in your system, a requirement for Navidrome to work properly. You may find the latest static build for your platform here: https://johnvansickle.com/ffmpeg/