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>KeepAlive</key>
        <true/>
        <key>WorkingDirectory</key>
        <string>/opt/navidrome</string>
        <key>StandardOutPath</key>
        <string>/opt/navidrome/navidrome.log</string>
        <key>StandardErrorPath</key>
        <string>/opt/navidrome/navidrome.log</string>
    </dict>
</plist>

File ownership and permissions

A LaunchAgent runs as your own user, not as root. All files must therefore belong to your user. If you created /opt/navidrome with sudo, the folder belongs to root and Navidrome cannot write to it.

Set the owner and the permissions like this:

# Give the whole folder to your user
sudo chown -R "$(whoami):staff" /opt/navidrome

# Make the binary executable
chmod 755 /opt/navidrome/navidrome

# Restrict the config file, as it can contain secrets
chmod 600 /opt/navidrome/navidrome.toml

# Create the data folder and keep it private.
# Use the path that you set in the DataFolder option.
mkdir -p /opt/navidrome/data
chmod 700 /opt/navidrome/data

# Create the log file and keep it private
touch /opt/navidrome/navidrome.log
chmod 600 /opt/navidrome/navidrome.log

# launchd refuses a plist that other users can write
chmod 644 ~/Library/LaunchAgents/navidrome.plist

This table shows the required values:

Access to protected folders

Correct file permissions are not always sufficient. macOS has a second, independent privacy system. It blocks some folders even when the file permissions permit access. A service started by launchd gets no permissions from your terminal, so this problem is common.

These folders are blocked:

• ~/Desktop, ~/Documents and ~/Downloads
• ~/Music/Music, the Apple Music library folder
• All external and network volumes in /Volumes

These folders are not blocked:

• ~/Music itself, but not the Music subfolder in it
• /Users/Shared
• /opt and other folders outside your home folder

The simplest solution is to keep your music in a folder that macOS does not block, for example /Users/Shared/Music. Then you do not need any of the steps below.

Symptoms

When macOS blocks your music folder, Navidrome does not report a clear error. Look for these signs instead:

• The library is empty after a scan, and no track is found.

• The log contains this line, which gives the wrong reason:

  level=warning msg="Scanner: Target folder does not exist." error="open .: operation not permitted"
  

  The folder does exist. The permission is the real cause.

There is a third symptom that is easy to miss. The first time Navidrome reads a blocked folder, macOS shows a permission dialog, and Navidrome waits for your answer. If you do not see the dialog, the scan seems to freeze, and the log shows:

level=error msg="Scan failed" error="library count: context canceled"

How to give access

Two methods are possible. Both work.

1. Answer the dialog. Click Allow when the dialog appears. macOS then adds an entry under System Settings > Privacy & Security > Files & Folders. You can switch it on and off there later.
2. Give Full Disk Access. Use this method if you did not see the dialog, or if you closed it:
   • Open System Settings > Privacy & Security > Full Disk Access.
   • Click +, then press Cmd+Shift+G and enter /opt/navidrome.
   • Select the navidrome binary and set the switch to on.
   • Restart the service.

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

"navidrome" is damaged and can't be opened. You should move it to the Bin.

sudo xattr -d com.apple.quarantine /path/to/navidrome