Navidrome is a self-hosted music server and streamer, compatible with the Subsonic/Airsonic API. This Home Assistant Add-on wraps the official deluan/navidrome Docker image and adds HA Supervisor integration.

Any Subsonic client works out of the box: DSub, Symfonium, Ultrasonic, Feishin and more.

#Wiki Pages

Page	Purpose
Installation	Add repository, install, configure and start.
Configuration	All ND_ environment variable options explained.
First Start	Create admin account, point to music folder.
Persistence	Database, cache and music paths.
Troubleshooting	Common symptoms and fixes.

#Minimum Operating Model

HA Add-on → Navidrome Web UI + Subsonic API :4533
Navidrome  → music folder (ND_MUSICFOLDER)
Data       → /data (database, cache)

#Step 1 — Add Repository

1. Open Home Assistant.
2. Go to Settings → Add-ons → Add-on Store.
3. Open ⋮ → Repositories.
4. Add:

https://github.com/pol4rfuchs/ha-apps

#Step 2 — Install

1. Search for Navidrome in the Add-on Store.
2. Click Install and wait for the image download.

#Step 3 — Configure

Set at minimum ND_MUSICFOLDER in the Configuration tab before starting.

ND_MUSICFOLDER: "/media/music"

#Step 4 — Start

1. Enable Start on boot.
2. Click Start.
3. Open Web UI button (port 4533).

All options map 1:1 to Navidrome environment variables.

#Required

Option	Default	Description
ND_MUSICFOLDER	/media/music	Required. Path to your music library.

#General

Option	Default	Description
ND_DATAFOLDER	/data	Database and cache location.
ND_SCANSCHEDULE	@every 24h	Auto-scan schedule. 0 = disabled.
ND_LOGLEVEL	info	error / warn / info / debug / trace
ND_ENABLEDOWNLOADS	true	Allow track downloads from the UI.
ND_JUKEBOX_ENABLED	false	Play audio on server hardware.

#External Integrations

Option	Default	Description
ND_LASTFM_ENABLED	false	Last.fm scrobbling and metadata.
ND_LISTENBRAINZ_ENABLED	false	ListenBrainz scrobbling.
ND_SPOTIFY_ID	—	Spotify Client ID for artist images.
ND_SPOTIFY_SECRET	—	Spotify Client Secret.

#Reverse Proxy / SSO

Option	Description
ND_REVERSEPROXYUSERHEADER	SSO header for transparent login (e.g. Remote-User).
ND_REVERSEPROXYWHITELIST	CIDRs allowed to send the proxy header.

#1. Open the Web UI

http://homeassistant.local:4533

#2. Create Admin Account

On first open, Navidrome prompts you to create an admin account. Save these credentials securely.

#3. Trigger a Library Scan

1. Log in with your admin account.
2. Go to Settings → Personal or wait for the automatic scan.
3. To trigger manually: Settings → Library → Scan.

#4. Connect a Subsonic Client

Field	Value
Server URL	http://homeassistant.local:4533
Username	Your Navidrome username
Password	Your Navidrome password
API version	Auto-detected by most clients

Source	Typical path	Notes
USB / HDD via HA	/media/music	HA mounts external drives here.
SMB (Samba add-on)	/share/music	Shared network drives.
NFS mount	/share/nfs	Network file system mounts.

Always use absolute paths. Relative paths inside the container will not resolve to your music.

/data/
├── navidrome.db    # Library database (artists, albums, tracks, ratings)
└── cache/          # Transcoding cache and artwork cache

#Backup

Home Assistant backups include the add-on /data directory automatically. The music files themselves are not backed up — they live outside /data in your media folder.

1. Settings → System → Backups → Create Backup.
2. For rollback, restore the Navidrome add-on data partition.
3. After restore, restart the add-on and verify library access.

Symptom	Cause	Fix
Web UI not opening	Port not mapped.	Check port 4533 in the Network tab.
No music showing	Wrong ND_MUSICFOLDER path.	Verify path is accessible and trigger a scan.
Scan runs but finds nothing	Permission issue on music folder.	Check HA media mount and folder permissions.
Subsonic client cannot connect	Wrong server URL or credentials.	Use http://HA-IP:4533.
Transcoding fails	ffmpeg not present.	The official Navidrome image includes ffmpeg — verify image is up to date.
Artwork not loading	Cache issue or missing artwork.	Clear browser cache; trigger a full rescan.

#License

This is an unofficial, community-maintained Home Assistant add-on wrapper for deluan/navidrome. Navidrome is licensed under GPL-3.0. The add-on wrapper is MIT.