Navidrome

Stream a private music library with Subsonic clients and native library management.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Navidrome

Stream a private music library with Subsonic clients and native library management.

Choose the native configuration deployment. Persistent application data lives in /data; mount or populate a separate music volume at /music.
Review Automatic app setup to create the first administrator. Existing users prevent bootstrap from running again.
Native YAML settings include scanning, transcoding, backups, Subsonic clients and supported external music metadata services.

Customize deployment inputs (1)

Local HTTP port port: portDefault: 4533

Save this as inputs.json and adjust the values before initialization.

{
  "port": 4533
}

selfhost app --directory ./navidrome init navidrome --method native --inputs inputs.json

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./navidrome start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd navidrome
docker compose -f compose.yaml up -d

Review the portable Compose and native configuration before starting.
The default listener is local-only. Add an authenticated HTTPS proxy before exposing private data.
Create your administrator on the first visit. Import music into the music volume or replace its mount with a read-only library path in a custom setup.
Native backups cover the database, not your music. Keep a separate media backup.

Before configuring integrations

Navidrome uses its own local database. Back up the data volume and preserve your media separately.
External authentication settings trust an upstream authentication proxy. Restrict direct access before trusting identity headers.
The version check and user list are read-only actions. Library scans require confirmation.
Selfhost does not upload media or configure transcoding binaries for you.
External authentication does not provision an OIDC client directly. Provider and proxy configuration must be completed separately.

Navidrome integrations

Compose service: navidrome. These operations use the profile saved when this deployment is created.

External header authentication requires a trusted proxy that removes spoofed headers. Restrict ExtAuth.TrustedSources before enabling it.
Database backups do not include your music library. Keep media backups separately.

Initialize and connect

Supported setup modes: bootstrap.

Creates the first administrator only. Existing installations are never reset. Library paths and media access remain under your control.

Setup fields

Administrator username username: string · requiredDefault: "admin"Length: 1 to 64 characters
Administrator password password: secret · requiredLength: 12 to 128 characters

Save onboarding.json, replace example values and supply env: secrets privately through your shell. Empty apps adds no links; add explicit links when this profile supports them.

{
  "mode": "bootstrap",
  "inputs": {
    "username": "admin",
    "password": "env:SELFHOST_PASSWORD"
  },
  "apps": []
}

selfhost app --directory ./navidrome setup navidrome
selfhost app --directory ./navidrome setup-plan navidrome onboarding.json
selfhost app --directory ./navidrome setup-apply navidrome onboarding.json --revision REVIEWED_REVISION

Setup modes, secret references and recovery

Native settings

Changes use the app’s native YAML file. Unrelated settings are preserved.

Supported fields (127)

Address address: string · advanced
Port port: integer · advanced
UnixSocketPerm unixsocketperm: string · advanced
EnforceNonRootUser enforcenonrootuser: boolean · advanced
MusicFolder musicfolder: string · advanced
DataFolder datafolder: string · advanced
CacheFolder cachefolder: string · advanced
LogLevel loglevel: string · advanced
LogFile logfile: string · advanced
SessionTimeout sessiontimeout: string · advanced
BaseURL baseurl: string · advanced
BasePath basepath: string · advanced
BaseHost basehost: string · advanced
BaseScheme basescheme: string · advanced
UILoginBackgroundURL uiloginbackgroundurl: string · advanced
UIWelcomeMessage uiwelcomemessage: string · advanced
MaxSidebarPlaylists maxsidebarplaylists: integer · advanced
EnableTranscodingConfig enabletranscodingconfig: boolean · advanced
EnableDownloads enabledownloads: boolean · advanced
EnableExternalServices enableexternalservices: boolean · advanced
EnableM3UExternalAlbumArt enablem3uexternalalbumart: boolean · advanced
EnableInsightsCollector enableinsightscollector: boolean · advanced
EnableScheduledDBAnalyze enablescheduleddbanalyze: boolean · advanced
EnableMediaFileCoverArt enablemediafilecoverart: boolean · advanced
TranscodingCacheSize transcodingcachesize: string · advanced
ImageCacheSize imagecachesize: string · advanced
AlbumPlayCountMode albumplaycountmode: string · advanced
EnableArtworkPrecache enableartworkprecache: boolean · advanced
AutoImportPlaylists autoimportplaylists: boolean · advanced
DefaultPlaylistPublicVisibility defaultplaylistpublicvisibility: boolean · advanced
PlaylistsPath playlistspath: string · advanced
SmartPlaylistRefreshDelay smartplaylistrefreshdelay: string · advanced
AutoTranscodeDownload autotranscodedownload: boolean · advanced
DefaultDownsamplingFormat defaultdownsamplingformat: string · advanced
RecentlyAddedByModTime recentlyaddedbymodtime: boolean · advanced
PreferSortTags prefersorttags: boolean · advanced
EnableNaturalSorting enablenaturalsorting: boolean · advanced
IgnoredArticles ignoredarticles: string · advanced
IndexGroups indexgroups: string · advanced
FFmpegPath ffmpegpath: string · advanced
MPVPath mpvpath: string · advanced
CoverArtPriority coverartpriority: string · advanced
CoverArtQuality coverartquality: integer · advanced
EnableWebPEncoding enablewebpencoding: boolean · advanced
ArtistArtPriority artistartpriority: string · advanced
ArtistImageFolder artistimagefolder: string · advanced
DiscArtPriority discartpriority: string · advanced
LyricsPriority lyricspriority: string · advanced
EnableGravatar enablegravatar: boolean · advanced
EnableFavourites enablefavourites: boolean · advanced
EnableStarRating enablestarrating: boolean · advanced
EnableUserEditing enableuserediting: boolean · advanced
EnableArtworkUpload enableartworkupload: boolean · advanced
MaxImageUploadSize maximageuploadsize: string · advanced
MaxImageSize maximagesize: string · advanced
EnableSharing enablesharing: boolean · advanced
ShareURL shareurl: string · advanced
DefaultShareExpiration defaultshareexpiration: string · advanced
DefaultDownloadableShare defaultdownloadableshare: boolean · advanced
DefaultTheme defaulttheme: string · advanced
DefaultLanguage defaultlanguage: string · advanced
DefaultUIVolume defaultuivolume: integer · advanced
UISearchDebounceMs uisearchdebouncems: integer · advanced
UICoverArtSize uicoverartsize: integer · advanced
EnableReplayGain enablereplaygain: boolean · advanced
EnableCoverAnimation enablecoveranimation: boolean · advanced
EnableNowPlaying enablenowplaying: boolean · advanced
UIPlaybackReportInterval uiplaybackreportinterval: string · advanced
GATrackingID gatrackingid: string · advanced
EnableLogRedacting enablelogredacting: boolean · advanced
AuthRequestLimit authrequestlimit: integer · advanced
AuthWindowLength authwindowlength: string · advanced
EnableScrobbleHistory enablescrobblehistory: boolean · advanced
Agents agents: string · advanced
Scanner / Enabled scanner-enabled: boolean · advanced
Scanner / Schedule scanner-schedule: string · advanced
Scanner / WatcherWait scanner-watcherwait: string · advanced
Scanner / ScanOnStartup scanner-scanonstartup: boolean · advanced
Scanner / Extractor scanner-extractor: string · advanced
Scanner / ArtistJoiner scanner-artistjoiner: string · advanced
Scanner / ArtistSplitExceptions scanner-artistsplitexceptions: string_list · advanced
Scanner / GenreSeparators scanner-genreseparators: string · advanced
Scanner / GroupAlbumReleases scanner-groupalbumreleases: boolean · advanced
Scanner / FollowSymlinks scanner-followsymlinks: boolean · advanced
Scanner / IgnoreDotFolders scanner-ignoredotfolders: boolean · advanced
Scanner / PurgeMissing scanner-purgemissing: string · advanced
Transcoding / MaxConcurrent transcoding-maxconcurrent: integer · advanced
Transcoding / MaxConcurrentPerUser transcoding-maxconcurrentperuser: integer · advanced
Transcoding / EnableCancellation transcoding-enablecancellation: boolean · advanced
Subsonic / AppendSubtitle subsonic-appendsubtitle: boolean · advanced
Subsonic / AppendAlbumVersion subsonic-appendalbumversion: boolean · advanced
Subsonic / ArtistParticipations subsonic-artistparticipations: boolean · advanced
Subsonic / DefaultReportRealPath subsonic-defaultreportrealpath: boolean · advanced
Subsonic / EnableAverageRating subsonic-enableaveragerating: boolean · advanced
Subsonic / LegacyClients subsonic-legacyclients: string · advanced
Subsonic / MinimalClients subsonic-minimalclients: string · advanced
LastFM / Enabled lastfm-enabled: boolean · advanced
LastFM / ApiKey lastfm-apikey: secret · advanced
LastFM / Secret lastfm-secret: secret · advanced
LastFM / Language lastfm-language: string · advanced
LastFM / ScrobbleFirstArtistOnly lastfm-scrobblefirstartistonly: boolean · advanced
Deezer / Enabled deezer-enabled: boolean · advanced
Deezer / Language deezer-language: string · advanced
ListenBrainz / Enabled listenbrainz-enabled: boolean · advanced
ListenBrainz / BaseURL listenbrainz-baseurl: string · advanced
ListenBrainz / ArtistAlgorithm listenbrainz-artistalgorithm: string · advanced
ListenBrainz / TrackAlgorithm listenbrainz-trackalgorithm: string · advanced
Jellyfin / Enabled jellyfin-enabled: boolean · advanced
Jellyfin / ServerName jellyfin-servername: string · advanced
Jellyfin / ExposedPublicUsers jellyfin-exposedpublicusers: string · advanced
Jellyfin / AutoDiscovery jellyfin-autodiscovery: boolean · advanced
Jellyfin / QuickConnect jellyfin-quickconnect: boolean · advanced
Jellyfin / MaxConcurrentStreams jellyfin-maxconcurrentstreams: integer · advanced
Prometheus / Enabled prometheus-enabled: boolean · advanced
Prometheus / MetricsPath prometheus-metricspath: string · advanced
Prometheus / Password prometheus-password: secret · advanced
Backup / Count backup-count: integer · advanced
Backup / Path backup-path: string · advanced
Backup / Schedule backup-schedule: string · advanced
Plugins / Enabled plugins-enabled: boolean · advanced
Plugins / Folder plugins-folder: string · advanced
Plugins / CacheSize plugins-cachesize: string · advanced
Plugins / AutoReload plugins-autoreload: boolean · advanced
Plugins / LogLevel plugins-loglevel: string · advanced
ExtAuth / TrustedSources extauth-trustedsources: string · advanced
ExtAuth / UserHeader extauth-userheader: string · advanced
ExtAuth / LogoutURL extauth-logouturl: string · advanced

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./navidrome config navidrome
selfhost app --directory ./navidrome plan navidrome changes.json
selfhost app --directory ./navidrome apply navidrome changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

App actions

Show version

Show the installed Navidrome version.

selfhost app --directory ./navidrome action navidrome check-version

List user accounts

List local users without changing their accounts.

selfhost app --directory ./navidrome action navidrome list-users

Scan music library

Run an incremental scan of the configured libraries.

selfhost app --directory ./navidrome action navidrome scan-library

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

navidrome: deluan/navidrome:0.64.2

0.64.2 deluan/navidrome:0.64.2
Local Docker HTTP startup, native configuration roundtrip, declared read-only actions and container recreation with persistent volumes passed. First administrator setup and initialized state after recreation passed. Native file bytes used a fixture volume because this host did not share bind directories; host file sharing remains unverified. External provider login and version upgrades require separate validation.

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Navidrome documentation