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. You can put any of the configuration options below in this file. Example of a configuration file for Windows (should be similar for Linux, just use forward slashes for paths):

# This is just an example! Please see available options below to customize Navidrome to your needs
LogLevel = 'DEBUG'
ScanSchedule = '@every 1h'
TranscodingCacheSize = '150MiB'
MusicFolder = 'C:\Users\JohnDoe\Music'  # IMPORTANT: Use single quotes for paths in Windows

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.

Ex. of usage (Windows):

C:\> navidrome --configfile "c:\User\johndoe\navidrome.toml"

Command Line Arguments

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

C:\> navidrome --musicfolder "c:\User\johndoe\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 "./music"
DataFolder ND_DATAFOLDER Folder to store application data (DB, cache…) "./data"
LogLevel ND_LOGLEVEL Log level. Useful for troubleshooting. Possible values: error, warn, info, debug, trace "info"
Address ND_ADDRESS IP address the server will bind to and :: (all IPs)
BaseUrl ND_BASEURL Base URL (only the path part) to configure Navidrome behind a proxy (ex: /music) Empty
Port ND_PORT HTTP port Navidrome will use 4533

Advanced configuration

In config file As an env var Description Default Value
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
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
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
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 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
EnableReplayGain ND_ENABLEREPLAYGAIN Enable ReplayGain options in the UI true
EnableSharing ND_ENABLESHARING Enable the Sharing feature false
EnableStarRating ND_ENABLESTARRATING Enable 5-star ratings in the UI true
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
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)
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"
LastFM.ApiKey ND_LASTFM_APIKEY ApiKey Navidrome project’s shared ApiKey
LastFM.Enabled ND_LASTFM_ENABLED Set this to false to completely disable integration true
LastFM.Language ND_LASTFM_LANGUAGE Two letter-code for language to be used to retrieve biographies from "en"
LastFM.Secret ND_LASTFM_SECRET Shared Secret Navidrome project’s shared Secret
ListenBrainz.BaseURL ND_LISTENBRAINZ_BASEURL Set this to override the default ListenBrainz base URL (useful with self-hosted solutions like Maloja*
ListenBrainz.Enabled ND_LISTENBRAINZ_ENABLED Set this to false to completely disable ListenBrainz integration true
MaxSidebarPlaylists ND_MAXSIDEBARPLAYLISTS Set the maximum number of playlists shon in the UI’s sidebar. Note that a very large number can cause UI performance issues. 100
PasswordEncryptionKey* ND_PASSWORDENCRYPTIONKEY Passphrase used to encrypt passwords in the DB. Click here for details -
PlaylistsPath ND_PLAYLISTSPATH Where to search for and import playlists from. Can be a list of folders/globs (separated by : (or ; on Windows). Paths are relative to MusicFolder ".:**/**" (meaning MusicFolder and all its subfolders)
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"
RecentlyAddedByModTime ND_RECENTLYADDEDBYMODTIME Uses music files’ modification time when sorting by “Recently Added”. Otherwise use import time false
ReverseProxyUserHeader* ND_REVERSEPROXYUSERHEADER HTTP header containing user name from authenticated proxy "Remote-User"
ReverseProxyWhitelist* ND_REVERSEPROXYWHITELIST Comma separated list of IP CIDRs which are allowed to use reverse proxy authentication, empty means “deny all” Empty
Scanner.Extractor ND_SCANNER_EXTRACTOR Select metadata extractor implementation. Options: taglib or ffmpeg "taglib"
Scanner.GenreSeparators ND_SCANNER_GENRESEPARATORS List of separators to split genre tags ";/,"
ScanSchedule ND_SCANSCHEDULE Configure periodic scans using “cron” syntax. To disable it altogether, set it to "0" "@every 1m"
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 "24h"
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
SubsonicArtistParticipations ND_SUBSONICARTISTPARTICIPATIONS When requesting artist’s albums, include albums where the artist participates (ex: Various Artists compilations) false
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
UIWelcomeMessage ND_UIWELCOMEMESSAGE Add a welcome message to the login screen Empty


  • 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”

Last modified February 19, 2023: typo: fix wrong spell (#109) (1ce756f)