Navidrome

https://www.navidrome.org/docs
Admin
Navidrome is a self-hosted music streaming server that supports multiple clients and provides...
Tokens:103,035
Snippets:909
Trust Score:9.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### navidrome service install examples

Source: https://www.navidrome.org/docs/usage/admin/cli/service

Two examples of installing the service. The first uses `--user` and `--configfile`; the second uses `--working-directory` with the `svc` alias.

```bash
# Install the service with a config file, run by the navidrome user
sudo navidrome service install --user navidrome --configfile /etc/navidrome/navidrome.toml

```

```bash
# Install with a different working directory
sudo navidrome svc install --working-directory /var/lib/navidrome

```

--------------------------------

### navidrome service start example

Source: https://www.navidrome.org/docs/usage/admin/cli/service

Example of starting the service using the `svc` alias.

```bash
sudo navidrome svc start

```

--------------------------------

### navidrome plugin info examples

Source: https://www.navidrome.org/docs/usage/admin/cli/plugin

Examples of showing details for an installed plugin and checking a downloaded package.

```bash
# Show details for an installed plugin
navidrome plugin info my-plugin

# Check a downloaded package before you install it
navidrome plugin info ./my-plugin-1.2.0.ndp
```

--------------------------------

### Install and start Navidrome service

Source: https://www.navidrome.org/docs/installation/macos

Installs the Navidrome service for the current user and starts it. The --user flag is required to avoid running as root.

```bash
sudo /opt/navidrome/navidrome service install --user "$(whoami)" -c /opt/navidrome/navidrome.toml
sudo /opt/navidrome/navidrome service start
```

--------------------------------

### navidrome backup restore examples

Source: https://www.navidrome.org/docs/usage/admin/cli/backup

Examples of restoring a backup from the default folder, from another folder, and with Docker Compose (stopping the server first, running the restore, then starting the server).

```bash
# Restore a backup from the Backup.Path folder
navidrome backup restore --backup-file navidrome_backup_2026.04.01_04.00.00.db

# Restore a backup from another folder
navidrome backup restore --backup-file /mnt/backups/navidrome/navidrome_backup_2026.04.01_04.00.00.db

# With Docker Compose, stop the server first
docker compose stop navidrome
docker compose run --rm navidrome backup restore --backup-file navidrome_backup_2026.04.01_04.00.00.db
docker compose start navidrome
```

--------------------------------

### Example navidrome.toml for Windows

Source: https://www.navidrome.org/docs/usage/configuration/options

Example configuration file for Windows. Includes a note to use single quotes for paths, and sets the FFmpegPath to a typical Windows installation path.

```toml
# 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-options

LogLevel = 'DEBUG'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'

# IMPORTANT: Use single quotes for paths in Windows

MusicFolder = 'C:\Users\JohnDoe\Music'

# Set this to the path of your ffmpeg executable

FFmpegPath = 'C:\Program Files\ffmpeg\bin\ffmpeg.exe'
```

--------------------------------

### Example navidrome.toml for macOS

Source: https://www.navidrome.org/docs/usage/configuration/options

Example configuration file for macOS. Sets the music folder and FFmpegPath to the default Homebrew installation path.

```toml
# 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-options

LogLevel = 'DEBUG'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'
MusicFolder = '/Users/JohnDoe/Music'

# This is the default path for Homebrew installed ffmpeg

FFmpegPath = '/opt/homebrew/bin/ffmpeg'
```

--------------------------------

### Enable and start Navidrome service

Source: https://www.navidrome.org/docs/installation/linux

Use systemctl to enable the Navidrome service to start on boot and start it immediately.

```bash
sudo systemctl enable --now navidrome

```

--------------------------------

### navidrome plugin list examples

Source: https://www.navidrome.org/docs/usage/admin/cli/plugin

Examples of listing plugins as a table and as JSON.

```bash
# List installed plugins as a table
navidrome plugin list

# List installed plugins as JSON
navidrome plugin list -f json
```

--------------------------------

### navidrome backup create examples

Source: https://www.navidrome.org/docs/usage/admin/cli/backup

Examples of creating a backup to the default folder (Backup.Path) and to a custom folder using the `--backup-dir` flag.

```bash
# Back up to the folder in Backup.Path
navidrome backup create

# Back up to another folder
navidrome backup create --backup-dir /mnt/backups/navidrome
```

--------------------------------

### Install and configure Navidrome service with NSSM (command line)

Source: https://www.navidrome.org/docs/installation/windows

Bypasses the GUI and configures the service entirely from the command line. Sets the executable, working directory, display name, user account, log files, and log rotation. The 'sc start' command starts the service.

```bash
nssm install Navidrome "C:\Services\navidrome\navidrome.exe"
nssm set Navidrome AppDirectory "C:\Services\navidrome\"
nssm set Navidrome DisplayName Navidrome
# The username and password of the user account under which the service will run.
nssm set Navidrome ObjectName "username" "password"
nssm set Navidrome AppStdout "C:\Services\navidrome\navidrome.log"
nssm set Navidrome AppStderr "C:\Services\navidrome\navidrome.log"
nssm set Navidrome AppRotateFiles 1
nssm set Navidrome AppRotateSeconds 86400
nssm set Navidrome AppRotateBytes 10240

# Start the service
sc start Navidrome
```

--------------------------------

### Install, start, and check status of Navidrome service with WinSW

Source: https://www.navidrome.org/docs/installation/windows

Commands to install, start, and check the status of the Navidrome service using the WinSW configuration file (navidrome.xml). Run from an administrator command prompt.

```bash
winsw install navidrome.xml
winsw start navidrome.xml
winsw status navidrome.xml
```

--------------------------------

### navidrome plugin enable example

Source: https://www.navidrome.org/docs/usage/admin/cli/plugin

Example of enabling a plugin.

```bash
navidrome plugin enable my-plugin
```

--------------------------------

### navidrome plugin edit examples

Source: https://www.navidrome.org/docs/usage/admin/cli/plugin

Examples of setting config, reading config from stdin, granting all users and write access, and limiting libraries.

```bash
# Set a plugin's config
navidrome plugin edit my-plugin --config '{"apiKey":"abc123"}'

# Read the config from stdin
cat config.json | navidrome plugin edit my-plugin --config-file -

# Give access to all users and let the plugin write to libraries
navidrome plugin edit my-plugin --all-users --write-access

# Limit the plugin to two libraries
navidrome plugin edit my-plugin --libraries 1,2
```

--------------------------------

### navidrome service start syntax

Source: https://www.navidrome.org/docs/usage/admin/cli/service

Syntax for starting the service.

```bash
navidrome service start

```

--------------------------------

### Examples: navidrome pls list

Source: https://www.navidrome.org/docs/usage/admin/cli/pls

Two examples of listing playlists: all as CSV, and one user's playlists as JSON.

```bash
# List all playlists as CSV
navidrome pls list

# List the playlists of one user as JSON
navidrome pls list --user alice --format json
```

--------------------------------

### Example MPV audio device list on Linux

Source: https://www.navidrome.org/docs/usage/features/jukebox

Example output from the `mpv --audio-device=help` command on Linux, showing the device names and descriptions.

```text
List of detected audio devices:
  'auto' (Autoselect device)
  'alsa' (Default (alsa))
  'alsa/jack' (JACK Audio Connection Kit)
  'alsa/default:CARD=Headphones' (bcm2835 Headphones, bcm2835 Headphones/Default Audio Device)

  ...

  'jack' (Default (jack))
  'sdl' (Default (sdl))
  'sndio' (Default (sndio))
```

--------------------------------

### navidrome user list examples

Source: https://www.navidrome.org/docs/usage/admin/cli/user

Examples for listing users as CSV and as JSON.

```bash
# List users as CSV
navidrome user list

# List users as JSON
navidrome user list --format json
```

--------------------------------

### Install .deb with dpkg and fix dependencies

Source: https://www.navidrome.org/docs/installation/linux

Install the package with dpkg, then run apt install -f to resolve any missing dependencies.

```bash
sudo dpkg -i ./navidrome_0.XX.X_amd64.deb
sudo apt install -f

```

--------------------------------

### Examples: navidrome pls import

Source: https://www.navidrome.org/docs/usage/admin/cli/pls

Four examples of importing M3U files: one file, many files for a user, a synced playlist from the library, and a Docker Compose mount example.

```bash
# Import one file
navidrome pls import ./road-trip.m3u

# Import many files for one user
navidrome pls import --user alice ./playlists/*.m3u

# Import a playlist from the library and keep it synced with the file
navidrome pls import --sync "/music/Playlists/Favorites.m3u"

# With Docker Compose, mount the files so the container can read them
docker compose run --rm -v ./playlists:/playlists navidrome pls import /playlists/road-trip.m3u
```

--------------------------------

### Example MPV audio device list on macOS

Source: https://www.navidrome.org/docs/usage/features/jukebox

Example output from the `mpv --audio-device=help` command on macOS, showing the device names and descriptions.

```text
List of detected audio devices:
  'auto' (Autoselect device)
  'coreaudio/AppleGFXHDAEngineOutputDP:10001:0:{D109-7950-00005445}' (BenQ EW3270U)
  'coreaudio/AppleUSBAudioEngine:Cambridge Audio :Cambridge Audio USB Audio 1.0:0000:1' (Cambridge Audio USB 1.0 Audio Out)
  'coreaudio/BuiltInSpeakerDevice' (MacBook Pro-Lautsprecher)
```

--------------------------------

### Install .deb with apt

Source: https://www.navidrome.org/docs/installation/linux

Install the downloaded .deb package using apt, which automatically resolves and installs dependencies like ffmpeg.

```bash
sudo apt install ./navidrome_0.XX.X_linux_amd64.deb

```

--------------------------------

### Create and start Navidrome service with Shawl

Source: https://www.navidrome.org/docs/installation/windows

Run from an administrator command prompt. Uses absolute paths for the executable and configuration file. The 'sc start' command starts the service after creation.

```bash
shawl add --name Navidrome -- "C:\Services\navidrome\navidrome.exe" -c "C:\Services\navidrome\navidrome.toml"
sc start Navidrome
```

--------------------------------

### Install Navidrome using pkg

Source: https://www.navidrome.org/docs/installation/freebsd

Use the package tool (pkg) to install Navidrome from a binary package. Follow any on-screen instructions to complete the installation.

```shell
pkg install navidrome
```

--------------------------------

### Docker volume mount example

Source: https://www.navidrome.org/docs/getting-started

Example of mounting a music folder as read-only in Docker. Ensure the path matches your actual music directory.

```bash
-v /path/to/music:/music:ro
```

--------------------------------

### Example navidrome.toml for Unix-based systems

Source: https://www.navidrome.org/docs/usage/configuration/options

Example configuration file for Unix-based systems. Sets log level, scanner schedule, transcoding cache size, and music folder. Note: This is just an example; see available options for customization.

```toml
# 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-options

LogLevel = 'DEBUG'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'
MusicFolder = '/mnt/music'
```

--------------------------------

### Examples: navidrome pls export

Source: https://www.navidrome.org/docs/usage/admin/cli/pls

Three examples of exporting playlists: all to a folder, one user's playlists, and one playlist to a folder.

```bash
# Export all playlists to a folder
navidrome pls export --output ./playlists

# Export the playlists of one user
navidrome pls export --user alice --output ./playlists

# Export one playlist to a folder
navidrome pls export --playlist "Road Trip Mix" --output ./playlists
```

--------------------------------

### Examples: navidrome pls

Source: https://www.navidrome.org/docs/usage/admin/cli/pls

Two examples of exporting a playlist to stdout or to a file using the `--playlist` and `--output` flags.

```bash
# Print a playlist to stdout
navidrome pls --playlist "Road Trip Mix"

# Write a playlist to a file
navidrome pls --playlist "Road Trip Mix" --output ./road-trip.m3u8
```

--------------------------------

### navidrome plugin rescan example

Source: https://www.navidrome.org/docs/usage/admin/cli/plugin

Example of picking up a new `.ndp` file copied into the plugins folder.

```bash
# Pick up a new .ndp file you copied into the plugins folder
navidrome plugin rescan
```

--------------------------------

### Update system and install ffmpeg

Source: https://www.navidrome.org/docs/installation/linux

Run these commands to update the system and install ffmpeg, a required dependency for Navidrome.

```bash
sudo apt update
sudo apt upgrade
sudo apt install vim ffmpeg

```

--------------------------------

### Complete Jukebox configuration example

Source: https://www.navidrome.org/docs/usage/features/jukebox

A complete example configuration showing how to enable Jukebox mode, define devices, and set a default device. Includes comments explaining each option.

```toml
# Enable/Disable Jukebox mode
Jukebox.Enabled = true

# List of registered devices, syntax:
#  "symbolic name " - Symbolic name to be used in UI's
#  "device" - MPV audio device name, do mpv --audio-device=help to get a list

Jukebox.Devices = [
    # "symbolic name " "device"
    [ "internal",     "coreaudio/BuiltInSpeakerDevice" ],
    [ "dac",          "coreaudio/AppleUSBAudioEngine:Cambridge Audio :Cambridge Audio USB Audio 1.0:0000:1" ]
]

# Device to use for Jukebox mode, if there are multiple entries above.
# Using device "auto" if missing
Jukebox.Default = "dac"
```

--------------------------------

### navidrome plugin validate examples

Source: https://www.navidrome.org/docs/usage/admin/cli/plugin

Examples of validating an installed plugin and a package file.

```bash
# Check an installed plugin
navidrome plugin validate my-plugin

# Check a package file
navidrome plugin validate ./my-plugin-1.2.0.ndp
```

--------------------------------

### Example index.yaml for adding an app

Source: https://www.navidrome.org/docs/developers/adding-apps

Complete example of an index.yaml file with required and optional fields, including platforms, API, description, screenshots, and keywords. Use this as a template when adding a new app to the catalog.

```yaml
name: My Music App
url: https://example.com/my-app
repoUrl: https://github.com/example/my-app  # Optional - used for release tracking
# isOpenSource: false  # Uncomment if repo exists but source code is not public

platforms:
  android:
    store: https://play.google.com/store/apps/details?id=com.example.myapp
  ios:
    store: https://apps.apple.com/app/my-app/id123456789
  web: true
  linux: true

api: OpenSubsonic

description: A beautiful music player with offline support and gapless playback.

screenshots:
  # This is the image shown in the main catalog page. Must not be a logo or icon
  thumbnail: thumbnail.webp
  gallery:
    - screen1.webp
    - screen2.webp

keywords:
  - dlna
  - chromecast
  - carplay
  - android auto

```

--------------------------------

### navidrome user create examples

Source: https://www.navidrome.org/docs/usage/admin/cli/user

Examples for creating an admin user and a regular user with limited library access. Without `--library-ids`, the user can access all libraries; admins always can.

```bash
# Create an admin user
navidrome user create --username alice --email alice@example.com --admin

# Create a regular user who can access libraries 1 and 3 only
navidrome user create --username bob --name "Bob Smith" --library-ids 1,3
```

--------------------------------

### navidrome search rebuild examples

Source: https://www.navidrome.org/docs/usage/admin/cli/search

Examples of rebuilding the search index: first checking the database with `navidrome doctor`, then rebuilding. For Docker Compose, stop the server first, run the rebuild, then start it again.

```bash
# Check the database, then rebuild a corrupted search index
navidrome doctor
navidrome search rebuild

# With Docker Compose, stop the server first
docker compose stop navidrome
docker compose run --rm navidrome search rebuild
docker compose start navidrome
```

--------------------------------

### Update system packages

Source: https://www.navidrome.org/docs/installation/linux

Run these commands to update the system package lists and upgrade installed packages before starting the migration.

```bash
sudo apt update
sudo apt upgrade
```

--------------------------------

### Example .ndignore file with gitignore syntax

Source: https://www.navidrome.org/docs/usage/library/exclude-content

Place this file in the parent folder of your library (e.g., `~/Music/.ndignore`) to exclude content. It supports comments starting with '#', ignores all `.flac` files, ignores specific folders `/untagged/` and `/unsorted/`, and negates the `.flac` ignore rule for a favorite album. Note that brace expansion like `*.{flac,mp3}` is not supported.

```plaintext
# .ndignore supports comments starting with '#'

# Ignore all .flac
*.flac

# ignore specific folders
/untagged/
/unsorted/

# Negate the .flac ignore rule for a favorite album. 
!/thursday/taking-inventory-of-a-frozen-lake/*.flac

```

--------------------------------

### Start and verify Navidrome service

Source: https://www.navidrome.org/docs/installation/freebsd

Start the Navidrome service and verify it has started correctly. Navidrome listens on 127.0.0.1:4533 by default.

```shell
service navidrome onestart
service navidrome onestatus
```

--------------------------------

### Start and verify Navidrome service

Source: https://www.navidrome.org/docs/installation/linux

Reload systemd, start the Navidrome service, and check its status. After starting, verify access at http://localhost:4533.

```bash
sudo systemctl daemon-reload
sudo systemctl start navidrome.service
sudo systemctl status navidrome.service

```

--------------------------------

### artwork explain examples

Source: https://www.navidrome.org/docs/usage/admin/cli/artwork

Examples of using `navidrome artwork explain` with different ID forms and the `--live` flag. The first two explain the same album by bare ID and full artwork ID; the third walks the chain live; the fourth explains disc 2 using the disc kind and a colon-separated ID.

```bash
# Explain an album by its bare ID
navidrome artwork explain 6XTD9naRGpIrZLoA99pH1r

# The same album, by its full artwork ID
navidrome artwork explain al-6XTD9naRGpIrZLoA99pH1r

# Walk the chain again now
navidrome artwork explain al 6XTD9naRGpIrZLoA99pH1r --live

# Explain disc 2 of an album
navidrome artwork explain dc 6XTD9naRGpIrZLoA99pH1r:2
```

--------------------------------

### navidrome plugin disable example

Source: https://www.navidrome.org/docs/usage/admin/cli/plugin

Example of disabling a plugin.

```bash
navidrome plugin disable my-plugin
```

--------------------------------

### Build and install Navidrome from ports

Source: https://www.navidrome.org/docs/installation/freebsd

Switch to the port directory for Navidrome and run make install. The build process may take several minutes depending on your computer's speed.

```shell
cd /usr/ports/multimedia/navidrome
make install
```

--------------------------------

### navidrome user delete example

Source: https://www.navidrome.org/docs/usage/admin/cli/user

Example for deleting a user by username.

```bash
navidrome user delete --user alice
```

--------------------------------

### Enable Navidrome at system startup

Source: https://www.navidrome.org/docs/installation/freebsd

Enable the Navidrome service to run at system startup by setting navidrome_enable in /etc/rc.conf using sysrc.

```shell
sysrc navidrome_enable="YES"
```

--------------------------------

### navidrome service stop example

Source: https://www.navidrome.org/docs/usage/admin/cli/service

Example of stopping the service using the `svc` alias.

```bash
sudo navidrome svc stop

```

--------------------------------

### Enable Navidrome on startup

Source: https://www.navidrome.org/docs/installation/linux

Enable the Navidrome service to start automatically on boot.

```bash
sudo systemctl enable navidrome.service

```
Tokens:
Raw