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.

navidrome artwork

Sun, 13 Sep 2026 00:00:00 +0000

The artwork commands tell you why a cover is wrong or an artist image is missing, without opening the database. They also queue artwork to resolve again, one item at a time or in bulk. See Artwork resolution for how Navidrome picks an image.

Usage

navidrome artwork <subcommand> [flags]

All commands also accept the global flags.

Artwork kinds

Each kind of artwork has a short code. Not every subcommand accepts every kind.

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.

When the same option is set using multiple methods, Navidrome uses the following order of precedence (highest to lowest): environment variables, command line arguments, configuration file.

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.

External Integrations (A.K.A. Agents)

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

Navidrome uses external services (through agents) to enrich your music library with artist biographies, images, album covers, similar artists, and more. Multiple agents can be configured, and they are tried in priority order. If one fails or returns no results, the next one is tried.

How Agents Work

The Agents config option controls which agents are enabled and in what order. It accepts a comma-separated list of agent names.

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 in the Navidrome GitHub discussions.

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:

AudioMuse-AI

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

AudioMuse-AI is a self-hosted service that analyzes the actual audio content of your music library — tempo, timbre, energy, and other sonic characteristics — and uses that analysis to find songs that sound similar. Unlike the external metadata agents, which rely on third-party databases like Last.fm or Deezer, AudioMuse-AI works entirely from your own files, so it can find matches even for obscure or unreleased music.

It integrates with Navidrome through a plugin, the AudioMuse-AI-NV-plugin. Once set up, you get:

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.

navidrome backup

Sun, 13 Sep 2026 00:00:00 +0000

The backup commands make a copy of the Navidrome database, delete old copies, and restore a copy. Navidrome can also make backups on a schedule. See Automated Backup.

Backups go to the folder in the Backup.Path setting. Each backup file has a name like navidrome_backup_2026.04.01_04.00.00.db, with the date and time it was made.

Usage

navidrome backup <subcommand> [flags]

The alias bkp works too, so navidrome bkp create is the same as navidrome backup create.

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)

You can also configure a centralized folder for artist images using the ArtistImageFolder config option and adding image-folder to ArtistArtPriority. When configured, Navidrome will look for image files in that folder named after the artist’s MusicBrainz ID or name.

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 and enable the EnforceNonRootUser configuration option. 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
Your app must meet one of these availability requirements (apps that do not meet either will not be accepted):
- Open source: the repository must have at least 15 stars (GitHub, GitLab, Codeberg, or any Gitea/Forgejo host)
- Closed source: the app must be publicly available on an app store (e.g. Google Play, Apple App Store)
Images must be in WebP format, max 1200px (PNG/JPEG needs to be converted)
You’ll need a GitHub account to submit a pull request

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/:

Navidrome API v1

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

Work in progress

This API is still being designed and is not ready for implementation yet. Anything in it may change without notice. When it is ready, it will be announced in the Navidrome release notes. Feedback is welcome in GitHub Discussions.

Navidrome API v1 is Navidrome’s own HTTP API. It is separate from the Subsonic API.

Open the Navidrome API v1 Reference

The reference is generated from the OpenAPI spec in the Navidrome repository, so it always matches the latest development version of Navidrome.

navidrome doctor

Sun, 13 Sep 2026 00:00:00 +0000

The doctor command checks the database for problems. It only reads the database and never changes your data. Run it when Navidrome logs errors such as database disk image is malformed, or when every scan fails.

Usage

navidrome doctor

Flags

doctor has no flags of its own. It accepts the global flags.

Examples

# Check the database
navidrome doctor

# Stop a script when the database has problems
navidrome doctor || exit 1

# Check the database with Docker Compose
docker compose run --rm navidrome doctor

What it checks

doctor runs two checks.

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

navidrome inspect

Sun, 13 Sep 2026 00:00:00 +0000

The inspect command prints the tags of one or more music files, the way Navidrome reads them. Use it when an album shows up split in two, or a tag you set doesn’t appear in Navidrome. For each file it prints the raw tags stored in the file and the mapped tags Navidrome uses. See Tagging for how Navidrome maps tags.

Usage

navidrome inspect [flags] <file> [<file>...]

All commands also accept the global flags.

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.

Sharing

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

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.

The Sharing feature is enabled by default. To turn it off, set EnableSharing=false in your configuration file, or set the environment variable ND_ENABLESHARING=false.

navidrome missing

Sun, 13 Sep 2026 00:00:00 +0000

The missing commands list files marked as missing, and remap a missing file onto an existing one.

The scanner marks a file missing when it no longer finds it on disk. When you rename or move a file, the scanner normally reconnects it and carries over play counts, ratings, starred status, and bookmarks. If the scanner can’t match the two files, the old entry stays missing and the new file starts with no history. missing fix does that remap by hand.

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

navidrome plugin

Sun, 13 Sep 2026 00:00:00 +0000

The plugin commands list, check, configure, enable, and disable plugins. They do the same things as the plugin screens in the web UI. See Plugins for how the plugin system works.

Usage

navidrome plugin <subcommand> [flags]

All commands also accept the global flags.

Commands that work with installed plugins need the plugin system enabled. Plugins.Enabled is on by default. You can still use plugin info and plugin validate on a .ndp package file when the plugin system is disabled.

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:

navidrome pls

Sun, 13 Sep 2026 00:00:00 +0000

The pls commands list playlists, export them to M3U files, and import M3U files as playlists.

Navidrome also imports M3U files it finds in your library when it scans. You don’t need pls import for those. See AutoImportPlaylists and PlaylistsPath in Configuration Options.

Usage

navidrome pls --playlist <name-or-id> [--output <file>]
navidrome pls <subcommand> [flags]

pls with no subcommand exports one playlist. pls export does the same, and it can also export many playlists at once.

Jellyfin API (Experimental)

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

Starting with version 0.64.0, Navidrome can answer a subset of the Jellyfin API. Music apps built for Jellyfin can connect to Navidrome and play your library. You do not need a Jellyfin server.

Experimental

This API is new, and some clients may hit requests that Navidrome does not answer yet. It covers what a music client needs. Video, live TV and the Jellyfin admin dashboard are not part of it. Please report problems in GitHub issues.

navidrome scan

Sun, 13 Sep 2026 00:00:00 +0000

The scan command scans your music library for new, changed, and removed files. Use it to start a scan from a script, to force a full scan, or to scan only some folders.

Usage

navidrome scan [flags]

All commands also accept the global flags.

Flags

Flag	Default	Description
`-f, --full`	`false`	Check all folders and ignore modification times
`-t, --target`		Scan only this folder, as a `libraryID:folderPath` pair. Repeatable
`--target-file`		File with folders to scan, one `libraryID:folderPath` pair per line

Navidrome also has a --subprocess flag. The server uses it to run scans, so don’t pass it yourself.

navidrome search

Sun, 13 Sep 2026 00:00:00 +0000

The search command maintains the full-text search index.

Usage

navidrome search <subcommand> [flags]

All commands also accept the global flags.

Subcommands

Subcommand	Description
`rebuild`	Delete the search index and build it again from the library data

`search rebuild`

Deletes the full-text search index and builds it again from your library data. The index only holds copies of data stored elsewhere in the database, so you lose nothing. Navidrome checks the new index before it saves it.

navidrome service

Sun, 13 Sep 2026 00:00:00 +0000

The service commands install Navidrome as a service in your OS service manager, then start, stop, and check it. The service manager is systemd on most Linux systems, launchd on macOS, and the Service Control Manager on Windows. navidrome service --help shows the one your system uses.

The installation guides for Linux, macOS, and Windows show the full setup.

Usage

navidrome service <subcommand> [flags]

The alias svc works too, so navidrome svc status is the same as navidrome service status.

navidrome user

Sun, 13 Sep 2026 00:00:00 +0000

The user commands create, edit, list, and delete Navidrome users.

These commands need at least one admin user in the database. On a new install, create the first admin in the web UI.

Usage

navidrome user <subcommand> [flags]

All commands also accept the global flags.

Subcommands

Subcommand	Alias	Description
`create`	`c`	Create a user
`edit`	`e`	Change a user
`list`		List users
`delete`	`d`	Delete a user

`user create`

Creates a user. The command asks for the password twice. Press Enter with no password to cancel. There is no flag for the password, so run the command in a terminal. With docker run, add -it.

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 # must own the data folder and be able to read music folder(s). See Permissions below
 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.

Installing with Podman

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

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

Using `Podman Quadlet` :

Podman is created to run as both rootful (root user), and rootless (non-root user) modes. Quadlet is a generator tool embeded directly into Podman that translate your *.container files into systemd service. So you can enable/disable it to auto load at each session, like normal systemd service.

macOS Install

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

You can start Navidrome by double-clicking the binary, or by running it in a terminal. However, it then stops when you close the terminal window, and it does not start again when the Mac restarts.

To run Navidrome in the background, install it as a service with the navidrome service command. The service starts when the Mac starts, even before anyone logs in, and macOS restarts it if it crashes.

Get Navidrome

Create a folder for Navidrome, and make your user its owner:

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.

The providers below have partnered with us to offer officially supported, cloud-hosted solutions*.

PikaPods

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

Zenith Hosting

Offers 1-click deployments for Navidrome. Upload and manage music in your browser and use your own domain for Navidrome.

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)

navidrome artwork

Usage

Artwork kinds

Automated Backup

Configuring Backup with config.toml

Navidrome Configuration Options

Configuration File

External Integrations (A.K.A. Agents)

How Agents Work

How to Use Smart Playlists in Navidrome (Beta)

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

AudioMuse-AI

Externalized Authentication Quick Start

What is externalized authentication

Externalized Authentication

navidrome backup

Usage

Multi-Library Support

Overview

How Multi-Library Works

Default Library

Artwork location resolution

Artists

Security Considerations

Permissions

Encrypted passwords

Translations

Contributing with a Pull Request

Adding Client Apps to the Catalog

Prerequisites

Quick Start

Folder Structure

Navidrome API v1

navidrome doctor

Usage

Flags

Examples

What it checks

Monitoring Navidrome

Overview

Jukebox mode

Introduction

Missing Files

Overview

Subsonic API Compatibility

Supported Subsonic API endpoints

navidrome inspect

Usage

Exclude Content From Library

Overview

Key behaviors

Sharing

Enabling and Disabling Sharing

navidrome missing

Anonymous Data Collection

Overview

Key Principles

What Will Be Collected?

Scrobbling

Last.fm

navidrome plugin

Usage

Plugins

What Plugins Can Do

navidrome pls

Usage

`search rebuild`

`user create`

Using `docker-compose` :

Using `Podman Quadlet` :