Skip to content

docs: add macOS bind mount caveat for Docker installation #368

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
laker-93 wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: add macOS bind mount caveat for Docker installation #368

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
94f5dec
docs: add macOS bind mount caveat for Docker installation
laker-93 May 28, 2026
2a6eb52
Fix wording for Docker-managed volumes in macOS section
laker-93 May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions content/en/docs/installation/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,3 +58,11 @@ $ docker run -d \
file. For `docker` cli use the `-e` parameter. Ex: `-e ND_SESSIONTIMEOUT=24h`.
- If you want to use a [configuration file](/docs/usage/configuration/options/#configuration-file) with Navidrome running in Docker,
you can create a `navidrome.toml` config file in the `/data` folder and set the option `ND_CONFIGFILE=/data/navidrome.toml`.

### MacOS Docker Desktop: bind mount caveat

When running Navidrome on Docker Desktop for macOS, using a host bind mount for the `/data` and `/music` directories may lead to filesystem-related issues such as disk I/O errors under certain workloads.

This appears to be related to the filesystem translation layer between macOS (APFS) and the Linux filesystem used inside the Docker VM (via VirtioFS / shared file systems). Under heavy or frequent disk activity (e.g. SQLite writes or library scanning), some users have reported instability or I/O errors.

A more reliable alternative on macOS is to use a Docker-managed volumes.