How to customize Navidrome to your environment
Navidrome allows some customization using environment variables, loading from a configuration fileor using command line arguments.
Configuration File
Navidrome tries to load the configuration from a navidrome.toml file in the current workingdirectory, if it exists. You can create this file and put any of the configuration options belowin it. Example of a configuration file (select your OS):
- Example:
- Windows
- macOS
- Unix-based systems
# 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-optionsLogLevel = 'DEBUG'ScanSchedule = '@every 24h'TranscodingCacheSize = '150MiB'# IMPORTANT: Use single quotes for paths in WindowsMusicFolder = 'C:\Users\JohnDoe\Music'# Set this to the path of your ffmpeg executableFFmpegPath = '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-optionsLogLevel = 'DEBUG'ScanSchedule = '@every 24h'TranscodingCacheSize = '150MiB'MusicFolder = '/Users/JohnDoe/Music'# This is the default path for Homebrew installed ffmpegFFmpegPath = '/usr/local/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-optionsLogLevel = 'DEBUG'ScanSchedule = '@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:
- Example:
- Windows
- macOs
- Unix-based systems
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 libraryunder your home directory:
- Example:
- Windows
- macOs
- Unix-based systems
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_ andmake 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) | "./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" |
| Address | ND_ADDRESS | Address the server will bind to. Can be an IPv4 or IPv6. Also supports unix:/path/to/file for Unix socket files | 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 use | 4533 |
Advanced configuration
| In config file | As an environment variable | Description | Default Value |
|---|---|---|---|
| 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 |
| ArtistArtPriority* | ND_ARTISTARTPRIORITY | Configure the order to look for artist images. | artist.*, album/artist.*, external |
| 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) |
| HTTPSecurityHeaders.CustomFrameOptionsValue | ND_HTTPSECURITYHEADERS_CUSTOMFRAMEOPTIONSVALUE | 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" |
| 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" |
| 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 |
| 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 --pause %f --input-ipc-server=%s |
| 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 MUST be relative to MusicFolder | ".:**/**" (meaning MusicFolder and all its subfolders) |
| 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" |
| 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 | ";/," |
| Scanner.GroupAlbumReleases | ND_SCANNER_GROUPALBUMRELEASES | “true” groups albums with the same Artist + Album Title as one album; “false” splits re-issues (=different Release Date) into separate albums | false |
| 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 |
| 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 Unsplash.com |
| 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”. Validtime units are “s”, “m”, “h”.
- Sizes are specified as a number and an optional unit suffix, such as “1GB” or “150 MiB”. Defaultunit is bytes. Note: “1KB” == “1000”, “1KiB” == “1024”
- Transcoding can be required in some situations. For example: trying to playa WMA file in a webbrowser, will only work for nativelysupported formats by the browser you are using. (so playing that with Mozilla Firefox on Linux, will not work. Mozillaeven has their own guide about audiocodecs).
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can make it even better.
Sorry to hear that. Please tell us how we can improve.
Last modified August 26, 2024: Corrected spelling errors (#175) (ec27199)
