Navidrome

Development Environment

Mon, 01 Jan 0001 00:00:00 +0000

This is just a summary on how to get started. If you are stuck or have any questions, please join our Discord server and give us a shout on the #dev channel

Any IDE with good support for GoLang and JavaScript/Node can be used for Navidrome development. We suggest using Visual Studio Code, which has excellent support for both languages.

Using VSCode + Dev Container (Docker)

The project includes a VSCode Dev Container configuration for using with Docker. The Dev Container provides all dependencies out-of-the-box. If you prefer to install all dependencies yourself, or cannot/don’t want to install Docker for any reason, see the other sections below for step by step instructions for your OS.

Automated Backup

Sat, 21 Dec 2024 00:00:00 +0000

Navidrome version 0.54.x introduces a backup feature that allows the music server’s data to get periodically exported. This guide will walk you through configuring backups using both a configuration file and environment variables, where to locate the backups, and how to restore from a backup.

Note: The backup process ONLY backs up the database (users, play counts, etc.). It does NOT back up the music or the config.

Configuring Backup with config.toml

To configure backups using the navidrome.toml file, insert the following lines to set up backups:

Navidrome Configuration Options

Fri, 06 Jan 2017 00:00:00 +0000

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

Configuration File

Some options are only configurable using a configuration file. If you are using environment variables (ex: with Docker), you may not be able to set all options.

If you want to use a configuration file with Docker, you can do so by creating a navidrome.toml config file in the host folder that is mapped to your /data volume. Docker installations automatically look for a navidrome.toml file in the /data folder.

External Integrations

Wed, 04 Jan 2017 00:00:00 +0000

Last.fm

Navidrome can use Last.fm to retrieve artists biographies, top songs, similar artists and album covers. It can also send your scrobbles to Last.fm. For these features to work, you’ll need to set the config options LastFM.ApiKey and LastFM.Secret. You can obtain these values by creating a free API account in Last.fm:

Go to https://www.last.fm/api/account/create and create an API account. Only the Application Name field is mandatory:

After submitting the form, you can get the API Key and Shared Secret from the Account Created page:

How to Use Smart Playlists in Navidrome (Beta)

Mon, 02 Jan 2017 00:00:00 +0000

Smart Playlists in Navidrome offer a dynamic way to organize and enjoy your music collection. They are created using JSON objects stored in files with a .nsp extension. These playlists are automatically updated based on specified criteria, providing a personalized and evolving music experience.

Beta Feature

Smart Playlists are currently in beta and may have some limitations. Please report any issues or suggestions to the Navidrome GitHub issues page.

Creating Smart Playlists

To create a Smart Playlist, you need to define a JSON object with specific fields and operators that describe the criteria for selecting tracks. The JSON object is stored in a .nsp file Here are some examples to get you started:

Tagging Guidelines

Mon, 02 Jan 2017 00:00:00 +0000

Why Proper Tagging is Important

Navidrome organizes your music library entirely based on the metadata tags in your audio files. Unlike some music players, it does not use folder names or file names to group tracks (why?). This means that having clean and consistent tags is crucial for your music to display correctly. Proper tagging ensures that albums aren’t split up, artists are listed correctly, and you can easily browse or search for your music in Navidrome.

Creating New Themes

Mon, 01 Jan 0001 00:00:00 +0000

Themes in Navidrome are simple Material-UI themes. They are basic JS objects, that allow you to override almost every visual aspect of Navidrome’s UI.

Steps to create a new theme:

Create a new JS file in the ui/src/themes folder that exports an object containing your theme. Create the theme based on the ReactAdmin/Material UI documentation below. See the existing themes for examples.
Add a themeName property to your theme. This will be displayed in the theme selector
Add your new theme to the ui/src/themes/index.js file
Start the application, your new theme should now appear as an option in the theme selector

Before submitting a pull request to include your theme in Navidrome, please test your theme thoroughly and make sure it is formatted with the Prettier rules found in the project (ui/src/.prettierrc.js). Also, don’t forget to add lots of screenshots!

Using custom tags with Navidrome

Mon, 02 Jan 2017 00:00:00 +0000

Overview

As all tags imported are stored and indexed in the database, to improve performance and reduce storage requirements, Navidrome only imports a predefined set of tags. The complete list of default tags imported are listed here.

However, Navidrome supports importing and using custom tags from your music files. Custom tags allow you to extend the metadata beyond the default supported tags. This functionality can be configured via the configuration file.

Customizing Persistent IDs in Navidrome

Mon, 02 Jan 2017 00:00:00 +0000

Persistent IDs in Navidrome

Persistent IDs (PIDs) are configurable identifiers introduced to provide stable references for Tracks and Albums in Navidrome, significantly improving how media is managed and identified.

Overview of Persistent IDs

Persistent IDs are unique, user-configurable identifiers for tracks and albums, enabling Navidrome to accurately detect and manage moved or re-tagged files, and disambiguate albums with identical names or duplicated entries.

Key Features

Configurable and Flexible: Users can define their PID structure using various tags, including musicbrainz_trackid, albumid, discnumber, tracknumber, title, folder, albumartistid, catalognum, Discogs IDs, or even custom tags
Accurate File Detection: Navidrome recognizes moved or re-tagged files, preventing duplication or mismatches.
Album Disambiguation: Easily differentiate albums with identical names through custom tags like albumversion (e.g., Deluxe Editions).

Default Configuration

The default configuration prioritizes MusicBrainz IDs (MBIDs) when available:

Externalized Authentication Quick Start

Tue, 29 Jul 2025 00:00:00 +0000

What is externalized authentication

Externalized authentication allows you to use an external system to handle authentication for Navidrome. Instead of managing user credentials in Navidrome itself, the responsibility is delegated to an external authentication service.

The external system comprises a reverse proxy (nginx, Caddy, Traefik, etc.) and an authentication service (Authelia, Authentik, or any other authentication service that works with your reverse proxy).

For Beginners

If you’re new to reverse proxies, they act as intermediaries between your users and Navidrome. They can handle things like SSL certificates, load balancing, and authentication before requests reach Navidrome.

Externalized Authentication

Sat, 27 Apr 2024 00:00:00 +0000

For Beginners

Externalized authentication is a relatively advanced topic. You can check the Quick Start guide for a beginner-friendly introduction.

Security Note

Navidrome works out of the box behind a reverse proxy without enabling externalized authentication.

You only need to enable externalized authentication if you want the proxy to handle the authentication. In other cases, enabling the feature without securing the reverse proxy configuration can leave your Navidrome setup vulnerable to impersonation attacks.

Multi-Library Support

Fri, 18 Jul 2025 00:00:00 +0000

Overview

Navidrome supports multiple music libraries since v0.58.0, allowing you to organize your music into separate collections with user-specific access controls. This feature is perfect for:

Separating different types of content (music vs. audiobooks)
Organizing by quality (lossy vs. lossless)
Separating personal collections (family members, roommates)
Organizing by genre or era (classical, jazz, modern)
Managing different sources (official releases vs. bootlegs/live recordings)

How Multi-Library Works

Default Library

When Navidrome starts, it automatically creates a default library using your MusicFolder configuration. This becomes “Library 1” and all existing users automatically get access to it, ensuring backward compatibility.

Artwork location resolution

Thu, 05 Jan 2017 00:00:00 +0000

Artists

Fetching images for artists is controlled by the ArtistArtPriority config option. This is a comma-separated list of places to look for artist images. The default is artist.*, album/artist.*, external, meaning:

First try to find an artist.* image in the artist folder(s)
If not found, try to find an artist.* image in one of the album folders for this artist
If not found, try to fetch it from an external service
If not found, use the artist image placeholder (grey star image)

Albums

CoverArt fetching for albums is controlled by the CoverArtPriority config option. This is a comma-separated list of places to look for album art images. The default is cover.*, folder.*, front.*, embedded, external, meaning:

Security Considerations

Mon, 02 Jan 2017 00:00:00 +0000

Permissions

You should NOT run Navidrome as root. Ideally you should have it running under its own user. Navidrome only needs read-only access to the Music Folder, and read-write permissions to the Data Folder.

Encrypted passwords

To be able to keep compatibility with the Subsonic API and its clients, Navidrome needs to store user’s passwords in its database. By default, Navidrome encrypts the passwords in the DB with a shared encryption key, just for the sake of obfuscation as this key can be easily found in the codebase.

Translations

Mon, 01 Jan 0001 00:00:00 +0000

Translations are currently managed in POEditor. If you want to contribute new translations or help reviewing/proofreading any of the existing ones, please join our Discord server, channel #translations, for translation efforts coordination and to get further instructions.

Contributing with a Pull Request

Alternatively, you can submit a pull request with your proposed changes directly to our project in GitHub. This method requires you to have a GitHub account and some basic knowledge of Git.

Adding Client Apps to the Catalog

Mon, 01 Jan 0001 00:00:00 +0000

Want to list your app in the Compatible Client Apps catalog? This guide explains how to submit your app or update an existing entry.

Prerequisites

Your app must support the OpenSubsonic, Subsonic, or Navidrome API
You’ll need a GitHub account to submit a pull request
Images must be in WebP format, max 1200px (PNG/JPEG needs to be converted)

Quick Start

Fork the navidrome/website repository
Create a folder for your app in assets/apps/ using kebab-case (e.g., my-awesome-app)
Add an index.yaml file with your app’s metadata
Add a thumbnail image and optional gallery screenshots
Convert (or resize) images if needed:
```
npm run convert:images my-awesome-app
```
Validate your entry using the provided scripts:
```
npm run validate:app my-awesome-app
```
Submit a pull request

Folder Structure

Each app has its own folder under assets/apps/:

Monitoring Navidrome

Mon, 08 Jul 2024 00:00:00 +0000

Currently, Navidrome supports monitoring and alerting using Prometheus/OpenMetrics standard. Example Grafana dashboard:

Overview

Prometheus is a service that takes data from a metrics endpoint and collects it. Grafana is a dashboard service that can take data from a Prometheus server and display it. Navidrome has an easy way to create a metrics endpoint that Prometheus can use. Once you point Prometheus to this endpoint, and Grafana to your Prometheus server, you will be able to monitor your Navidrome instance.

Jukebox mode

Mon, 23 Oct 2023 00:00:00 +0000

Introduction

Navidrome’s Jukebox feature is a built-in functionality that allows users to play music directly to the server’s audio hardware. This essentially turns your server into a jukebox, enabling you to play songs or playlists remotely through a supported Subsonic client. With the Jukebox feature, you can control the audio playback in real-time, just like you would with any other media player. It’s a convenient way to enjoy your music collection without the need for additional hardware or software. Ideal for parties, background music, or personal enjoyment, this feature enhances the versatility of your Navidrome server setup.

Missing Files

Mon, 02 Jan 2017 00:00:00 +0000

Overview

When using Navidrome, you may encounter missing tracks or albums in your library. When moving or renaming files, Navidrome may not be able to match the old versions of your files with the new ones when scanning your library. This can result in “ghost” (grayed out) tracks or albums in your library.

Only admins can see the missing tracks and albums in the library:

Missing files are not removed from the database on new scans to avoid inadvertently losing information like ratings, and play counts and references in playlists.

Subsonic API Compatibility

Mon, 01 Jan 0001 00:00:00 +0000

Supported Subsonic API endpoints

Navidrome is currently compatible with Subsonic API v1.16.1, with some exceptions.

OpenSubsonic extensions are being constantly added. For an up to date list of supported extensions, check here.

This is a (hopefully) up-to-date list of all Subsonic API endpoints implemented in Navidrome. Check the “Notes” column for limitations/missing behavior. Also keep in mind these differences between Navidrome and Subsonic:

Navidrome will not implement any video related functionality, it is focused on Music only
Navidrome supports multiple Music Libraries (Music Folders) with user-specific access controls
There are currently no plans to support browse-by-folder. Endpoints for this functionality (Ex: getIndexes, getMusicDirectory) returns a simulated directory tree, using the format: /Artist/Album/01 - Song.mp3.
Navidrome does not mark songs as played by calls to stream, only when scrobble is called with submission=true
IDs in Navidrome are always strings, normally MD5 hashes or UUIDs. This is important to mention because, even though the Subsonic API schema specifies IDs as strings, some clients insist in converting IDs to integers

System
`ping`
`getLicense`	Always valid ;)

Browsing
`getMusicFolders`	Returns all libraries accessible to the authenticated user
`getIndexes`	Doesn’t support `shortcuts`, nor direct children
`getMusicDirectory`
`getSong`
`getArtists`
`getArtist`
`getAlbum`
`getGenres`
`getArtistInfo`	Requires external integrations
`getArtistInfo2`	Requires external integrations
`getAlbumInfo`	Requires external integrations
`getAlbumInfo2`	Requires external integrations
`getTopSongs`	Requires Last.fm integration
`getSimilarSongs`	Requires Last.fm integration
`getSimilarSongs2`	Requires Last.fm integration

Album/Songs Lists
`getAlbumList`
`getAlbumList2`
`getStarred`
`getStarred2`
`getNowPlaying`
`getRandomSongs`
`getSongsByGenre`

Searching
`search2`	Doesn’t support Lucene queries, only simple auto complete queries
`search3`	Doesn’t support Lucene queries, only simple auto complete queries

Playlists
`getPlaylists`	`username` parameter is not implemented
`getPlaylist`
`createPlaylist`
`updatePlaylist`
`deletePlaylist`

Media Retrieval
`stream`
`download`	Accepts ids for Songs, Albums, Artists and Playlists. Also accepts transcoding options similar to `stream`
`getCoverArt`
`getLyrics`	Works with embedded lyrics and external files
`getAvatar`	If Gravatar is enabled and the user has an email, returns a redirect to their Gravatar. Or else returns a placeholder

Media Annotation
`star`
`unstar`
`setRating`
`scrobble`

Bookmarks
`getBookmarks`
`createBookmark`
`deleteBookmark`
`getPlayQueue`	`current` is a string id, not `int` as it shows in the official Subsonic API documentation
`savePlayQueue`

Sharing (if `EnableSharing` is `true`)
`getShares`
`createShare`
`updateShare`
`deleteShare`

Internet radio
`getInternetRadioStations`
`createInternetRadioStation`
`updateInternetRadioStation`
`deleteInternetRadioStation`

User Management
`getUser`	Ignores username parameter, and returns the user identified in the authentication. Roles reflect actual server capabilities and user permissions. For example: `downloadRole` depends on download being enabled, `jukeboxRole` depends on jukebox being enabled, etc. Note that some features like ratings and favorites are always available to all users regardless of roles
`getUsers`	Returns only the user identified in the authentication

Media library scanning
`getScanStatus`	Also returns the extra fields `lastScan` and `folderCount`
`startScan`	Accepts an extra `fullScan` boolean param, to force a full scan

Exclude Content From Library

Sat, 05 Jul 2025 00:00:00 +0000

Overview

Navidrome allows the usage of a .ndignore file to exclude content from being added to Navidrome’s library. These files can be used in the following ways:

A blank .ndignore file can be added to a directory, and as a result Navidrome will ignore that folder and its subfolders from being added to Navidrome’s library.
A .ndignore file also supports .gitignore syntax inside of it to set rules for content to exclude. This allows you to place a single file in your parent Music folder and then use a single file to establish rules on ignoring certain folders, filetypes, or files.

Key behaviors

Cascading: Patterns from parent directories apply to all subdirectories
Multiple files: You can place .ndignore files in different directories

A new or updated .ndignore file should be auto-detected by Navidrome, or can be detected with a Quick Scan.

Syntax Usage and Examples

A single .ndignore can be placed at the parent folder of your library and then syntax added to it.

Sharing

Mon, 02 Jan 2017 00:00:00 +0000

NOTE

Please be aware that the Sharing feature is still under active development, and improvements to the functionality are expected in future updates. Please report any issues or suggestions to the Navidrome GitHub issues page.

Navidrome has a “Sharing” feature which allows users to generate a shareable link for a track, album, artist, or playlist. This link can then be sent to friends, allowing them to listen or download the music without having an account on your Navidrome instance.

Anonymous Data Collection

Sun, 08 Dec 2024 00:00:00 +0000

Overview

Navidrome includes an anonymous usage statistics feature designed to help improve the project for all users. This page explains what data is collected, how it is used, and how to opt out if you prefer not to participate.

Key Principles

Anonymous Data Only: Navidrome collects only non-personal, anonymous data to guide future improvements.
What’s Collected: See Collected Data.
What’s NOT Collected: No emails, IP addresses, usernames, or other identifiable data. See Excluded Data.
Opt-Out Available: Enabled by default, but you can disable it anytime.
In-House Data Handling: Collected data goes to an open-source server hosted by the project—no third-party services.
Full Transparency: Logs and UI indicators show when data is sent and what it contains.

What Will Be Collected?

Below is a plain-English explanation of what each field is generally intended to represent. Each field corresponds to a piece of information about the running application or its environment:

Scrobbling

Mon, 01 Jan 0001 00:00:00 +0000

Navidrome allows you to easily scrobble your played songs to Last.fm and ListenBrainz.

Last.fm

Ensure you have the API Key and API Secret set according to the instructions in External Integrations.
Go to your user profile’s Personal Settings.
Toggle the option Scrobble to Last.fm, a new browser tab will open directing you to Last.fm.

If you are not logged in, then log in with your Last.fm credentials.

Click “Yes, allow access”.

Plugins

Sat, 31 Jan 2026 00:00:00 +0000

Navidrome supports a plugin system that allows you to extend its functionality with community-developed extensions. Plugins run in a secure WebAssembly sandbox, providing isolation from the main application while enabling powerful customizations.

Plugins are developed by the community. While they run in a secure sandbox, you should always review a plugin’s documentation and source code before installation.

What Plugins Can Do

Plugins can extend Navidrome in several ways:

Windows Install

Mon, 19 Aug 2024 00:00:00 +0000

MSI Install

Download and install the latest Navidrome MSI for the correct version of Windows (most likely AMD64). The installer will prompt for basic configuration options (port, directories etc). These can be left as default or customised to your setup. The service will be installed and started automatically, once the installer has completed you can go to [http://127.0.0.1:4533] (or whichever port you chose) in a browser and setup the first user. The navidrome.ini configuration file will be located in the installation folder (default: C:\Program Files\Navidrome).

Installing with Docker

Thu, 05 Jan 2017 00:00:00 +0000

Docker images are available for the linux/amd64, linux/arm/v6, linux/arm/v7 and linux/arm64 platforms. They include everything needed to run Navidrome.

Using `docker-compose` :

Create a docker-compose.yml file with the following content (or add the navidrome service below to your existing file):

services:
 navidrome:
 image: deluan/navidrome:latest
 user: 1000:1000 # should be owner of volumes
 ports:
 - "4533:4533"
 restart: unless-stopped
 environment:
 # Optional: put your config options customization here. Examples:
 # ND_LOGLEVEL: debug
 volumes:
 - "/path/to/data:/data"
 - "/path/to/your/music/folder:/music:ro"

Start it with docker-compose up -d. Note that the environment variables above are just an example and are not required. The values in the example are already the defaults

Linux Install

Thu, 05 Jan 2017 00:00:00 +0000

NOTE: These instructions were created for the Ubuntu distribution, and even though they contain specific Ubuntu/Debian instructions (ex: apt) the concepts are generic enough and can be applied on most Linux distributions, even on those not based on Debian (ex: CentOS and OpenSUSE)

Important note

The following steps have been tested on KGARNER7’s MACHINE! WHICH IS: Ubuntu 18.04 and should work on all version 16.04 and above as well as other Debian based distros. Throughout these instructions the commands will have placeholders for the user (<user>) and group (<group>) you want to run Navidrome under and the music folder path (<library_path>). If you are using an existing media library ensure the user has permissions to the media library.

Install Navidrome Using Pre-built Binary

To install Navidrome on a Linux system using a .deb file, you can follow a streamlined process that leverages the convenience of Debian package management. This method simplifies the installation by eliminating the need to manually download and extract binaries.

macOS Install

Wed, 04 Jan 2017 00:00:00 +0000

Navidrome can be ran by simply double-clicking the binary that has been downloaded from the release page or by running it in the command line. However, that will keep a terminal window open while Navidrome is running.

To have Navidrome running in the background, we can run it as a service. We define a service as shown below and save that in a file named navidrome.plist in the ~/Library/LaunchAgents/ folder.

The example shown assumes a few things:

FreeBSD Install

Tue, 03 Jan 2017 00:00:00 +0000

The following steps have been tested on FreeBSD 12 and 13. They should work on all versions 11.4 and above as well as other supported versions. All prerequisites will be automatically installed when using a package or if building from ports. Throughout these instructions the commands will have placeholders for the user (<user>) and group (<group>) you want to run Navidrome under and the music folder path (<library_path>). If you are using an existing media library ensure the user has permissions to the media library.

Community Maintained Packages

Mon, 01 Feb 2016 00:00:00 +0000

DISCLAIMER: These packages are not maintained by the Navidrome project, any issues should be reported to their authors.

Even though the Navidrome project does not provide any pre-packaged installation for specific platforms, there are some packages created and maintained by the community, that can simplify the setup on some systems.

Here is the list of packages for various OSes/Distributions, provided by Repology:

More packages available, with links to download/install instructions:

Managed Hosting

Sun, 10 Jan 2016 00:00:00 +0000

The following providers offer managed hosting for Navidrome. This can be a good option if you don’t want to manage your own server.

PikaPods

PikaPods has partnered with us to offer you an officially supported, cloud-hosted solution*.

Offers 1-click deployments for Navidrome with $5 free welcome credit. EU and US regions available. Includes daily backups and regular app updates.

Build from sources

Tue, 05 Jan 2016 00:00:00 +0000

Currently these instructions only work for Unix-based systems (Linux, macOS, BSD, …). If you are getting trouble trying to build Navidrome in a Windows system, please join our Discord server and ask for help, we will be glad to assist you

If you can’t find a pre-built binary for your platform, you should open an issue in the project’s GitHub page.

If you don’t want to wait, you can try to build the binary yourself, with the following steps.

Mon, 01 Jan 0001 00:00:00 +0000

Search Results

Mon, 01 Jan 0001 00:00:00 +0000

Navidrome

Development Environment

Using VSCode + Dev Container (Docker)

Automated Backup

Configuring Backup with config.toml

Navidrome Configuration Options

Configuration File

External Integrations

Last.fm

How to Use Smart Playlists in Navidrome (Beta)

Beta Feature

Creating Smart Playlists

Tagging Guidelines

Why Proper Tagging is Important

Creating New Themes

Steps to create a new theme:

Using custom tags with Navidrome

Overview

Customizing Persistent IDs in Navidrome

Persistent IDs in Navidrome

Overview of Persistent IDs

Key Features

Default Configuration

Externalized Authentication Quick Start

What is externalized authentication

For Beginners

Externalized Authentication

For Beginners

Security Note

Multi-Library Support

Overview

How Multi-Library Works

Default Library

Artwork location resolution

Artists

Albums

Security Considerations

Permissions

Encrypted passwords

Translations

Contributing with a Pull Request

Adding Client Apps to the Catalog

Prerequisites

Quick Start

Folder Structure

Monitoring Navidrome

Overview

Jukebox mode

Introduction

Missing Files

Overview

Subsonic API Compatibility

Supported Subsonic API endpoints

Exclude Content From Library

Overview

Key behaviors

Syntax Usage and Examples

Sharing

NOTE

Anonymous Data Collection

Overview

Key Principles

What Will Be Collected?

Scrobbling

Last.fm

Plugins

What Plugins Can Do

Windows Install

MSI Install

Installing with Docker

Using docker-compose :

Linux Install

Important note

Install Navidrome Using Pre-built Binary

macOS Install

FreeBSD Install

Community Maintained Packages

Managed Hosting

PikaPods

Build from sources

Using `docker-compose` :