Navidrome Configuration Options

How to customize Navidrome to your environment

Navidrome allows some customization using environment variables, loading from a configuration file or using command line arguments.

Configuration File

Navidrome tries to load the configuration from a navidrome.toml file in the current working directory, if it exists. You can create this file and put any of the configuration options below in it. Example of a configuration file (select your OS):

# This is just an example! Please see available options to customize Navidrome for your needs at

# https://www.navidrome.org/docs/usage/configuration-options/#available-options

LogLevel = 'DEBUG'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'

# IMPORTANT: Use single quotes for paths in Windows

MusicFolder = 'C:\Users\JohnDoe\Music'

# Set this to the path of your ffmpeg executable

FFmpegPath = 'C:\Program Files\ffmpeg\bin\ffmpeg.exe'
# This is just an example! Please see available options to customize Navidrome for your needs at

# https://www.navidrome.org/docs/usage/configuration-options/#available-options

LogLevel = 'DEBUG'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'
MusicFolder = '/Users/JohnDoe/Music'

# This is the default path for Homebrew installed ffmpeg

FFmpegPath = '/opt/homebrew/bin/ffmpeg'
# This is just an example! Please see available options to customize Navidrome for your needs at

# https://www.navidrome.org/docs/usage/configuration-options/#available-options

LogLevel = 'DEBUG'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'
MusicFolder = '/mnt/music'

You can also specify a different path for the configuration file, using the -c/--configfile option. Navidrome can load the configuration from toml, json, yml and ini files.

The example below assume you have created a navidrome.toml file in your home directory:

C:\> navidrome --configfile "c:\User\JohnDoe\navidrome.toml"
$ navidrome --configfile "/User/JohnDoe/navidrome.toml"
$ navidrome --configfile "/home/johndoe/navidrome.toml"

Command Line Arguments

You can set most of the config options below passing arguments to navidrome executable.

The example below shows how to set the MusicFolder using the command line, assuming you have your music library under your home directory:

C:\> navidrome --musicfolder "c:\User\JohnDoe\Music"
$ navidrome --musicfolder "/User/JohnDoe/Music"
$ navidrome --musicfolder "/mnt/music"

Please note that command line arguments must be all lowercase. For a list of all available command line options, just call navidrome --help.

Environment Variables

Any configuration option can be set as an environment variable, just add a the prefix ND_ and make it all uppercase. Ex: ND_LOGLEVEL=debug. See below for all available options

Available Options

Basic configuration

In config file As an env var Description Default Value
- ND_CONFIGFILE Load configurations from an external config file "./navidrome.toml"
MusicFolder ND_MUSICFOLDER Folder where your music library is stored. Can be read-only. This becomes the default library when using multi-library setup "./music"
DataFolder ND_DATAFOLDER Folder to store application data (DB) "./data"
CacheFolder ND_CACHEFOLDER Folder to store cache data (transcoding, images…) "<DataFolder>/cache"
LogLevel ND_LOGLEVEL Log level. Useful for troubleshooting. Possible values: error, warn, info, debug, trace "info"
LogFile ND_LOGFILE Path to log file for output. When specified, logs will be written to this file instead of stderr Empty (log to stderr)
Address ND_ADDRESS Address the server will bind to. Can be an IPv4, IPv6 or a UNIX socket file (unix:/path/to/file) 0.0.0.0 and :: (all IPs)
BaseUrl ND_BASEURL Base URL to configure Navidrome behind a proxy (examples: /music, https://music.example.com) Empty
Port ND_PORT HTTP port Navidrome will listen to 4533
EnableInsightsCollector ND_ENABLEINSIGHTSCOLLECTOR Controls whether the server will run its Anonymous Data Collection feature to help improve the project. true

Advanced configuration

In config file As an environment variable Description Default Value
Agents ND_AGENTS Comma-separated list of metadata agents to use for retrieving artist information, biographies, and images. Available agents: lastfm, spotify, and deezer. The order determines priority - agents are tried in the specified order until one succeeds. Only enabled and configured agents will be used. "lastfm,spotify,deezer"
AlbumPlayCountMode ND_ALBUMPLAYCOUNTMODE Change how album play count is computed. When set to "normalized", album play count will be divided by the number of album tracks "absolute"
AuthRequestLimit* ND_AUTHREQUESTLIMIT How many login requests can be processed from a single IP during the AuthWindowLength. Set to 0 to disable the limit rater 5
AuthWindowLength* ND_AUTHWINDOWLENGTH Window Length for the authentication rate limit "20s"
AutoImportPlaylists ND_AUTOIMPORTPLAYLISTS Enable/disable .m3u playlist auto-import true
AutoTranscodeDownload ND_AUTOTRANSCODEDOWNLOAD Use the client’s transcoding configuration for downloads, if the client does not specify the desired format. If false, the original format will be used, without any transcoding. false
DefaultPlaylistPublicVisibility ND_DEFAULTPLAYLISTPUBLICVISIBILITY Set imported playlists as public by default false
ArtistArtPriority* ND_ARTISTARTPRIORITY Configure the order to look for artist images. "artist.*, album/artist.*, external"
Backup.Path ND_BACKUP_PATH Path to store backups. Set to "" to disable backups. Click here for details "" (disabled)
Backup.Schedule ND_BACKUP_SCHEDULE Schedule for automatic backups. Use Cron syntax "" (disabled)
Backup.Count ND_BACKUP_COUNT Number of backups to keep 0 (disabled)
CoverArtPriority* ND_COVERARTPRIORITY Configure the order to look for cover art images. Use special embedded value to get embedded images from the audio files cover.*, folder.*, front.*, embedded, external
CoverJpegQuality ND_COVERJPEGQUALITY Set JPEG quality percentage for resized cover art images 75
Deezer.Enabled* ND_DEEZER_ENABLED Set this to false to completely disable Deezer integration for artist images true
Deezer.Language ND_DEEZER_LANGUAGE Language to be used by Deezer integration "en"
DefaultDownsamplingFormat ND_DEFAULTDOWNSAMPLINGFORMAT Format to transcode to when client requests downsampling (specify maxBitrate without a format) "opus"
DefaultLanguage ND_DEFAULTLANGUAGE Sets the default language used by the UI when logging in from a new browser. This value must match one of the file names in the resources/i18n. Ex: for Chinese Simplified it has to be zh-Hans (case sensitive) "en"
DefaultTheme ND_DEFAULTTHEME Sets the default theme used by the UI when logging in from a new browser. This value must match one of the options in the UI “Dark”
DefaultShareExpiration ND_DEFAULTSHAREEXPIRATION Sets the default expiration time for new shares (public links). Accepts durations like “24h” or “45m”. "8760h" (1 year)
DefaultDownloadableShare ND_DEFAULTDOWNLOADABLESHARE Sets the default downloadable state for new shares (public links). When enabled, newly created shares will be downloadable by default false
DefaultUIVolume ND_DEFAULTUIVOLUME Sets the default volume used by the UI when logging in from a new browser. This value must be between 0 and 100 100
EnableArtworkPrecache ND_ENABLEARTWORKPRECACHE Enable image pre-caching of new added music true
EnableCoverAnimation ND_ENABLECOVERANIMATION Controls whether the player in the UI will animate the album cover (rotation) true
EnableDownloads ND_ENABLEDOWNLOADS Enable the option in the UI to download music/albums/artists/playlists from the server true
EnableExternalServices ND_ENABLEEXTERNALSERVICES Set this to false to completely disable ALL external integrations, including the anonymous data collection and the nice login background images true
EnableFavourites ND_ENABLEFAVOURITES Enable toggling “Heart”/“Loved” for songs/albums/artists in the UI (maps to “Star”/“Starred” in Subsonic Clients) true
EnableGravatar ND_ENABLEGRAVATAR Use Gravatar images as the user profile image. Needs the user’s email to be filled false
EnableLogRedacting ND_ENABLELOGREDACTING Whether or not sensitive information (like tokens and passwords) should be redacted (hidden) in the logs true
EnableMediaFileCoverArt* ND_ENABLEMEDIAFILECOVERART If set to false, it will return the album CoverArt when a song CoverArt is requested true
EnableNowPlaying ND_ENABLENOWPLAYING Enable/disable the Now Playing feature that tracks what songs users are currently listening to. When disabled, the “Now Playing” functionality and admin panel will be unavailable true
EnableReplayGain ND_ENABLEREPLAYGAIN Enable ReplayGain options in the UI true
EnableScrobbleHistory ND_ENABLESCROBBLEHISTORY Enable/disable scrobble history true
EnableSharing ND_ENABLESHARING Enable the Sharing feature false
EnableStarRating ND_ENABLESTARRATING Enable 5-star ratings in the UI true
EnableTranscodingCancellation ND_ENABLETRANSCODINGCANCELLATION Enables transcoding cancellation when a client disconnects during streaming. When enabled, transcoding processes are stopped if the client closes the connection, saving server resources. Useful for preventing unnecessary transcoding work when users skip or stop playback false
EnableTranscodingConfig* ND_ENABLETRANSCODINGCONFIG Enables transcoding configuration in the UI false
EnableUserEditing ND_ENABLEUSEREDITING Enable regular users to edit their details and change their password true
ExtAuth.TrustedSources* ND_EXTAUTH_TRUSTEDSOURCES Comma separated list of IP CIDRs (or when listening on a UNIX socket the special value @) which are allowed to use reverse proxy authentication. Empty means “deny all”. Click here for details. Note: This option is unnecessary for most reverse proxy setups, only for authenticating reverse proxies. Empty
ExtAuth.UserHeader* ND_EXTAUTH_USERHEADER HTTP header containing the user name from an authenticating proxy. Click here for details. "Remote-User"
FFmpegPath ND_FFMPEGPATH Path to ffmpeg executable. Use it when Navidrome cannot find it, or you want to use a specific version Empty (search in the PATH)
GATrackingID ND_GATRACKINGID Send basic info to your own Google Analytics account. Must be in the format UA-XXXXXXXX Empty (disabled)
HTTPHeaders.FrameOptions ND_HTTPHEADERS_FRAMEOPTIONS Allows the X-Frame-Options header value to be set with a custom value. Ex: "SAMEORIGIN" "DENY"
IgnoredArticles ND_IGNOREDARTICLES List of ignored articles when sorting/indexing artists "The El La Los Las Le Les Os As O A"
ImageCacheSize ND_IMAGECACHESIZE Size of image (art work) cache. Set to "0" to disable cache "100MB"
Inspect.BacklogLimit ND_INSPECT_BACKLOGLIMIT Backlog limit for inspect request throttling 100
Inspect.BacklogTimeout ND_INSPECT_BACKLOGTIMEOUT Backlog timeout for inspect request throttling "1m"
Inspect.Enabled ND_INSPECT_ENABLED Enable/disable inspect endpoints true
Inspect.MaxRequests ND_INSPECT_MAXREQUESTS Maximum concurrent inspect requests 1
Jukebox.Enabled ND_JUKEBOX_ENABLED Enable Jukebox mode (play audio on server’s hardware) Click here for details false
Jukebox.AdminOnly ND_JUKEBOX_ADMINONLY By default, Jukebox mode is only available to Admins. Set this option to false to allow any valid user to control it true
Jukebox.Devices (cannot be set as an environment variable) List of devices that can be used by the Jukebox. Click here for details Empty (auto detect)
Jukebox.Default ND_JUKEBOX_DEFAULT Device to use for Jukebox mode, if there are multiple Jukebox.Devices entries. Click here for details Empty (auto detect)
LastFM.Enabled ND_LASTFM_ENABLED Set this to false to completely disable Last.fm integration true
LastFM.ApiKey* ND_LASTFM_APIKEY Last.fm API Key Empty
LastFM.Secret* ND_LASTFM_SECRET Last.fm API Secret Empty
LastFM.Language ND_LASTFM_LANGUAGE Two letter-code for language to be used to retrieve biographies from Last.fm "en"
LastFM.ScrobbleFirstArtistOnly ND_LASTFM_SCROBBLEFIRSTARTISTONLY When enabled, only the first artist will be scrobbled for tracks with multiple artists, instead of the display artist or concatenated list false
ListenBrainz.BaseURL ND_LISTENBRAINZ_BASEURL Set this to override the default ListenBrainz base URL (useful with self-hosted solutions like Maloja* https://api.listenbrainz.org/1/
ListenBrainz.Enabled ND_LISTENBRAINZ_ENABLED Set this to false to completely disable ListenBrainz integration true
LyricsPriority ND_LYRICSPRIORITY Controls the order and sources for fetching lyrics. Comma-separated list of sources checked in order: embedded (from tags), file extensions like .lrc, .txt, or any custom extension. Navidrome will search for lyrics files with the same name as the audio file but with the specified extension. ".lrc,.txt,embedded"
MaxSidebarPlaylists ND_MAXSIDEBARPLAYLISTS Set the maximum number of playlists shown in the UI’s sidebar. Note that a very large number can cause UI performance issues. 100
MPVPath ND_MPVPATH Path to mpv executable. Used for Jukebox mode Empty (search in PATH)
MPVCmdTemplate ND_MPVCMDTEMPLATE Cmd template used to construct the call of the mpv executable. Used for Jukebox mode mpv --audio-device=%d --no-audio-display %f --input-ipc-server=%s
PasswordEncryptionKey* ND_PASSWORDENCRYPTIONKEY Passphrase used to encrypt passwords in the DB. Click here for details -
PID.Album ND_PID_ALBUM Set the tag(s) to use as the Album ID. Click here for details musicbrainz_albumid|albumartistid,album,albumversion,releasedate
PID.Track ND_PID_TRACK Set the tag(s) to use as the Track ID. Click here for details musicbrainz_trackid|albumid,discnumber,tracknumber,title
PlaylistsPath ND_PLAYLISTSPATH Limit where to search for and import playlists from. Can be a list of folders/globs (separated by : (or ; on Windows). Paths MUST be relative to MusicFolder Empty (meaning any playlist files in your library will be imported)
PreferSortTags ND_PREFERSORTTAGS Use Sort_* tags to sort columns in the UI. false
Prometheus.Enabled ND_PROMETHEUS_ENABLED Enable extra endpoint with Prometheus metrics. false
Prometheus.MetricsPath ND_PROMETHEUS_METRICSPATH Custom path for Prometheus metrics. Useful for blocking unauthorized metrics requests. "/metrics"
Prometheus.Password ND_PROMETHEUS_PASSWORD Enables Basic Auth protection for Prometheus endpoint. User will be navidrome. Leave empty to disable Basic Auth protection. Empty (no password/authentication)
RecentlyAddedByModTime ND_RECENTLYADDEDBYMODTIME Uses music files’ modification time when sorting by “Recently Added”. Otherwise use import time false
Scanner.Enabled ND_SCANNER_ENABLED Enable/disable the scanner. Set to false to disable automatic scanning of the music library. true
Scanner.Schedule ND_SCANNER_SCHEDULE Schedule for automatic scans. Use Cron syntax 0 (disabled)
Scanner.WatcherWait ND_SCANNER_WATCHERWAIT Time to wait after a file change is detected before starting a scan. Useful to avoid scanning incomplete files. Set it to 0 to disable the watcher "5s"
Scanner.ScanOnStartup ND_SCANNER_SCANONSTARTUP Enable/disable scanning the music library on startup. Set to false to disable true
Scanner.ArtistJoiner ND_SCANNER_ARTISTJOINER Character string used to join multiple artists in display. Change this if you prefer a different separator between artist names " • "
Scanner.FollowSymlinks ND_SCANNER_FOLLOWSYMLINKS Whether to follow symbolic links when scanning directories. When enabled, the scanner will traverse symlinked directories and include their contents in the library. When disabled, symlinked directories are ignored during scanning true
Scanner.PurgeMissing ND_SCANNER_PURGEMISSING Controls when missing files, albums, and artists are purged from the database during scans. Possible values: "never" (default, just mark as missing), "always" (purge after every scan), "full" (purge only after a full scan). "never"
SearchFullString ND_SEARCHFULLSTRING Match query strings anywhere in searchable fields, not only in word boundaries. Useful for languages where words are not space separated false
SessionTimeout ND_SESSIONTIMEOUT How long Navidrome will wait before closing web ui idle sessions "48h"
ShareURL ND_SHAREURL Base URL for shared links. Useful when your server address is not a public (ex: when using Tailscale). See discussion here Empty (use server address)
SmartPlaylistRefreshDelay ND_SMARTPLAYLISTREFRESHDELAY How often to refresh Smart Playlists. Check the smart playlists docs "5s"
Spotify.ID* ND_SPOTIFY_ID Spotify Client ID. Required if you want Artist images Empty
Spotify.Secret* ND_SPOTIFY_SECRET Spotify Client Secret. Required if you want Artist images Empty
Subsonic.AppendSubtitle ND_SUBSONIC_APPENDSUBTITLE Append the subtitle tag to the song title in all Subsonic API responses true
Subsonic.ArtistParticipations ND_SUBSONIC_ARTISTPARTICIPATIONS When Subsonic clients request artist’s albums, include albums where the artist participates (ex: Various Artists compilations) false
Subsonic.DefaultReportRealPath ND_SUBSONIC_DEFAULTREPORTREALPATH Set to true to report the real path of the music files in the API. Can be customized individually for each client/player. This can be a security risk, so it is disabled by default false
Subsonic.LegacyClients ND_SUBSONIC_LEGACYCLIENTS List of clients that does not work with the new OpenSubsonic API improvements. "DSub"
Tags (cannot be set as an environment variable) Configure custom tags to be imported from your music files. Click here for details Empty
TLSCert ND_TLSCERT Path for the TLS certificate file, which should include the signature chain if any Empty (disable TLS)
TLSKey ND_TLSKEY Path for the TLS key file Empty (disable TLS)
TranscodingCacheSize ND_TRANSCODINGCACHESIZE Size of transcoding cache. Set to "0" to disable cache "100MB"
UILoginBackgroundUrl ND_UILOGINBACKGROUNDURL Change background image used in the Login page random music image from this Unsplash.com collection
UIWelcomeMessage ND_UIWELCOMEMESSAGE Add a welcome message to the login screen Empty
UnixSocketPerm ND_UNIXSOCKETPERM Set file permissions for Unix Socket File.* "0660"

Notes

  • Durations are specified as a number and a unit suffix, such as “24h”, “30s” or “1h10m”. Valid time units are “s”, “m”, “h”.
  • Sizes are specified as a number and an optional unit suffix, such as “1GB” or “150 MiB”. Default unit is bytes. Note: “1KB” == “1000”, “1KiB” == “1024”
  • Transcoding can be required in some situations. For example: trying to play a WMA file in a webbrowser, will only work for natively supported formats by the browser you are using. (so playing that with Mozilla Firefox on Linux, will not work. Mozilla even has their own guide about audio codecs).

Last modified December 13, 2025: feat: rename HTTPSecurityHeaders.CustomFrameOptionsValue to HTTPHeaders.FrameOptions (60f11cb)