Media, checked 2026-09-07
Navidrome: Docker configuration reference
Self-hosted music server and streamer exposing a Subsonic-compatible API to existing mobile and desktop clients.
At a glance
- Image:
docker.io/deluan/navidrome - Tags:
latest,0.63.2,0.63.1,0.63.0 - Licence: GPL-3.0
- Source: https://github.com/navidrome/navidrome
- Docs: https://www.navidrome.org/docs/
Ports
| Port | What listens | Source |
|---|---|---|
4533 | Default HTTP port for the web UI, the Subsonic API and streaming. Configurable with ND_PORT. | source for port 4533 |
Environment variables
| Variable | Required | What it does | Example | Source |
|---|---|---|---|---|
ND_MUSICFOLDER | No | Folder where the music library is mounted. Read-only access is enough; it becomes the default library. | /music | source for ND_MUSICFOLDER |
ND_DATAFOLDER | No | Folder for the SQLite database. Defaults to ./data, which the Docker image maps from /data. | /data | source for ND_DATAFOLDER |
ND_BASEURL | No | Base URL to set when Navidrome runs behind a proxy on a subpath or a different external hostname. | https://music.example.com | source for ND_BASEURL |
ND_ENABLEINSIGHTSCOLLECTOR | No | Controls the anonymous usage data collector that ships with the server, on by default. | false | source for ND_ENABLEINSIGHTSCOLLECTOR |
Volumes that must persist
| Path | What is in it | Source |
|---|---|---|
/data | Database and transcoding cache. The container needs write access here or it fails to start. | source for /data |
/music | The music library, normally mounted read-only. Navidrome only needs read and execute access to it. | source for /music |
Behind a reverse proxy
- Set ND_BASEURL when serving Navidrome from a subpath or a public URL different from the container's own address, or client apps mislink. source for this reverse-proxy note
- Route the proxy to the container's HTTP port, 4533 by default; change it with ND_PORT if the container itself is reconfigured. source for this reverse-proxy note
- The container must run with a user directive matching the UID:GID that owns the data folder, or startup fails opening the database file. source for this reverse-proxy note
Release timeline
| Version | Date | Breaking | What changed | Source |
|---|---|---|---|---|
v0.63.2 | 2026-07-11 | No | Fixes plugin host service failures being hidden, symlink resolution in the scanner, and a smart playlist validation bug. | source for release v0.63.2 |
v0.63.1 | 2026-07-09 | No | Fixes a 32-bit startup crash in the download binaries and buffered scrobble handling when a plugin is removed. | source for release v0.63.1 |
v0.63.0 | 2026-07-08 | No | Adds synced sidecar lyrics in multiple formats with word-by-word timing, exposed through the OpenSubsonic v2 lyrics extension. | source for release v0.63.0 |
v0.62.0 | 2026-06-08 | No | Adds the OpenSubsonic sonicSimilarity extension, enabling audio-based similarity and playlists through plugins. | source for release v0.62.0 |
v0.61.2 | 2026-04-12 | No | Clamps transcoding target channels to codec limits, plays WAV directly without needless transcoding, adds configurable max cover upload size. | source for release v0.61.2 |
If it is not coming up
- ECONNREFUSED / ENOTFOUND / connection to server at "postgres" port 5432 failed
- Coolify volume data lost after redeploy / a new empty volume is created every deploy
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-09-07. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.