Configuration Options
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 | 0.0.0.0 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 |
Last.fm ApiKey | Navidrome project’s shared ApiKey |
LastFM.Enabled | ND_LASTFM_ENABLED |
Set this to false to completely disable Last.fm integration |
true |
LastFM.Language | ND_LASTFM_LANGUAGE |
Two letter-code for language to be used to retrieve biographies from Last.fm | "en" |
LastFM.Secret | ND_LASTFM_SECRET |
Last.fm 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* | 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 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 Unsplash.com |
UIWelcomeMessage | ND_UIWELCOMEMESSAGE |
Add a welcome message to the login screen | Empty |
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”
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.