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_LOGLEVEL	info	error / warn / info / debug / trace
PUID	0	User ID Navidrome runs as. Match your music share's owner to avoid permission issues.
PGID	0	Group ID Navidrome runs as.

#UI

Option	Default	Description
ND_ENABLESTARRATING	true	Show star-rating controls in the UI.
ND_ENABLEFAVOURITES	true	Enable the favourites/heart feature.
ND_ENABLEDOWNLOADS	true	Allow track downloads from the UI.
ND_ENABLESHARING	false	Allow generating public share links.
ND_ENABLEGRAVATAR	false	Use Gravatar images for user avatars.
ND_MAXSIDEBARPLAYLISTS	100	Maximum number of playlists shown in the sidebar.

#Library

Option	Default	Description
ND_SCANNER_SCHEDULE	@every 24h	Auto-scan schedule. Empty = disabled. (Renamed from ND_SCANSCHEDULE.)
ND_AUTOIMPORTPLAYLISTS	true	Import .m3u playlist files found in the music folder.
ND_IGNOREDARTICLES	The El La Los Las Le Les Os As O A	Articles ignored when sorting artist/album names.
ND_INDEXGROUPS	A B C D E F G H I J K L M N O P Q R S T U V W X-Z(XYZ) #([^A-Za-z].*)	Grouping used for the A-Z index.
ND_COVERARTPRIORITY	embedded, cover.*, folder.*, front.*	Priority order for picking cover art.
ND_IMAGECACHESIZE	100MB	Disk cache size for resized cover art.

#Scanner / Extractor

Option	Default	Description
ND_SCANNER_EXTRACTOR	taglib	Metadata extractor backend: taglib or ffmpeg.

#Transcoding

Option	Default	Description
ND_TRANSCODINGCACHESIZE	100MB	Disk cache size for transcoded audio.
ND_DEFAULTDOWNSAMPLINGFORMAT	opus	Default format used when downsampling on the fly.

#Podcasts

Option	Default	Description
ND_PODCAST_EPISODEKEEPCOUNT	0	Number of downloaded episodes to keep per podcast. 0 = unlimited.
ND_PODCAST_EPISODEDOWNLOADCOUNT	0	Number of episodes to auto-download per podcast. 0 = disabled.

#Sessions / Security

Option	Default	Description
ND_SESSIONTIMEOUT	30m	Idle timeout before a web UI session expires.

#Scrobbling

Option	Default	Description
ND_LASTFM_ENABLED	false	Last.fm scrobbling and metadata.
ND_LASTFM_LANGUAGE	en	Language used for Last.fm metadata lookups.
ND_LISTENBRAINZ_ENABLED	false	ListenBrainz scrobbling.

Removed: Spotify integration (ND_SPOTIFY_ID / ND_SPOTIFY_SECRET) and the reverse-proxy SSO options (ND_REVERSEPROXYUSERHEADER / ND_REVERSEPROXYWHITELIST) are no longer exposed as add-on options.

#Jukebox

Option	Default	Description
ND_JUKEBOX_ENABLED	false	Play audio directly on the server's sound hardware. Requires privileged: true and ALSA device access.

#Playlists

Option	Default	Description
ND_DEFAULTPLAYLISTPUBLICVISIBILITY	false	New playlists are public by default when enabled.
ND_SMARTPLAYLISTREFRESHDELAY	5s	Delay before a smart playlist is refreshed after a change.

#Analytics

Option	Default	Description
ND_ENABLEINSIGHTSCOLLECTOR	false	Send anonymous usage insights to the Navidrome project.

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