Navidrome with Docker: Stream Your Own Music Collection (Linux, Windows, Mac)

What you get in one minute#

Navidrome is a free, self-hosted music server: you point it at a folder of music files you own, and you stream them to your phone, laptop or browser, like your own small Spotify.

Logo: the official Navidrome project (github.com/navidrome/navidrome)

It reads the tags inside your files, builds albums and artists, and talks to any app that speaks the Subsonic or OpenSubsonic API. It is for music only, uses few resources, and never changes your files.

At a glance:

• What it is: one container with a web player and a Subsonic-compatible API. Your music stays in your folder; Navidrome keeps only a database and a cache.
• Your files are safe: the music folder is mounted read-only (:ro). The docs say Navidrome only needs read access there.
• Apps: any Subsonic or OpenSubsonic client works; the project lists more than 100.
• Remote listening: use a VPN into your home network. Do not forward port 4533 on your router.
• Image name: the docs now say navidrome/navidrome (changed 16 October 2026). Older guides say deluan/navidrome. Docker Hub shows 0.64.2 on both.

How it fits together#

Your apps talk to one container on port 4533. It reads your music folder (read-only) and writes only to its own data folder. Away from home, the phone joins your VPN first.

Drawn for this guide from the official Docker page and security notes. The dashed HTTPS route is optional.

Before you start#

You need a computer that stays on, Docker with Compose, and a folder of tagged music files.

docker --version
docker compose version

Checklist:

• [ ] Docker and Compose work (the two commands above)
• [ ] Your music folder exists and its files have tags (see "What your library needs")
• [ ] Port 4533 is free on the machine
• [ ] The music folder is backed up (Navidrome does not back it up)
• [ ] For the HTTPS section only: a DNS name for the server and ports 80 and 443 free

Without Docker, the docs describe a Windows MSI installer, a macOS navidrome service install command and Linux .deb or tarball installs. This guide uses Docker so the steps match on all three systems.

Tested by DIY Lab Hub: not yet. The commands come from the official Docker page, the Dockerfile and the docs read in November 2026. We did not run them.

Step 1: Create the folders and the settings file#

We keep everything in ~/docker_volumes/navidrome, as all DIY Lab Hub guides do. A small .env file holds three values: the user that runs the container and the path to your music. The docs say that user must own the data folder and be able to read the music.

Linux#

mkdir -p ~/docker_volumes/navidrome/{data,backups}
cd ~/docker_volumes/navidrome
printf 'APP_UID=%s\nAPP_GID=%s\nMUSIC_DIR=%s\n' "$(id -u)" "$(id -g)" "$HOME/Music" > .env
chmod 600 .env
cat .env
ls -n "$HOME/Music" | head -5

If your music is elsewhere, edit the MUSIC_DIR line. The ls -n line shows the numeric owner of your music files.

Windows (PowerShell)#

New-Item -ItemType Directory -Force "$HOME\docker_volumes\navidrome\data","$HOME\docker_volumes\navidrome\backups" | Out-Null
Set-Location "$HOME\docker_volumes\navidrome"
$music = ("$HOME\Music" -replace '\\','/')
"APP_UID=1000`nAPP_GID=1000`nMUSIC_DIR=$music" | Set-Content -Encoding ascii .env
Get-Content .env

Windows has no Linux user IDs, so we use the docs' example 1000:1000. The Navidrome docs do not cover Docker Desktop on Windows and we did not test it. If Step 2 fails with a database error, see Troubleshooting.

Mac (Terminal)#

Same commands as Linux. Docker Desktop must be allowed to share the folder that holds your music; if a mount fails, check its file sharing settings.

Check it worked. cat .env (or Get-Content .env) shows a user number, a group number and the full path to your music.

Tip: Do not copy PUID and PGID from other Docker guides. The Navidrome docs say its image ignores them. Only the user: line in Compose sets the user.

Step 2: Write the Compose file and start Navidrome#

This is the official compose file with five changes: the image is pinned to 0.64.2, paths come from .env, data lives in ./data, nightly database backups are on, and the anonymous usage report is off. Your music mounts read-only.

Linux#

cd ~/docker_volumes/navidrome
cat > docker-compose.yml << 'EOF'
services:
  navidrome:
    image: navidrome/navidrome:0.64.2
    container_name: navidrome
    restart: unless-stopped
    user: "${APP_UID}:${APP_GID}"
    ports:
      - "4533:4533"
    environment:
      ND_ENABLEINSIGHTSCOLLECTOR: "false"
      ND_BACKUP_PATH: /backup
      ND_BACKUP_SCHEDULE: "0 3 * * *"
      ND_BACKUP_COUNT: "7"
    volumes:
      - "./data:/data"
      - "./backups:/backup"
      - "${MUSIC_DIR}:/music:ro"
EOF
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=50 navidrome

Windows (PowerShell)#

Set-Location "$HOME\docker_volumes\navidrome"
@'
services:
  navidrome:
    image: navidrome/navidrome:0.64.2
    container_name: navidrome
    restart: unless-stopped
    user: "${APP_UID}:${APP_GID}"
    ports:
      - "4533:4533"
    environment:
      ND_ENABLEINSIGHTSCOLLECTOR: "false"
      ND_BACKUP_PATH: /backup
      ND_BACKUP_SCHEDULE: "0 3 * * *"
      ND_BACKUP_COUNT: "7"
    volumes:
      - "./data:/data"
      - "./backups:/backup"
      - "${MUSIC_DIR}:/music:ro"
'@ | Set-Content -Encoding ascii docker-compose.yml
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=50 navidrome

Mac (Terminal)#

Same commands as Linux, with the same docker-compose.yml.

Check it worked. docker compose ps shows navidrome running. The docs say the log should show messages like these (their example, not our output):

Creating DB Schema
Scanner: Starting scan
Navidrome server is ready!

A second check, curl -s -o /dev/null -w "%{http_code}\n" http://localhost:4533/ping, should print 200. The /ping route is in the server source at the release tag, not in the docs. On Windows use curl.exe.

Tip: If the container stops at once, run docker compose logs navidrome. The two commonest errors, an unwritable data folder and an unreadable music folder, are in Troubleshooting with their exact text.

Step 3: Create the admin account and let it scan#

The first person to open the page creates the admin account. Do it yourself before you share the address.

Linux#

Open http://localhost:4533 on the machine, or http://<server-address>:4533 from another computer on your network. Enter a username and a long password, repeat it and press Create Admin. Watch the scan, and press Ctrl+C to leave the log:

cd ~/docker_volumes/navidrome
docker compose logs -f navidrome

Windows (PowerShell)#

Open http://localhost:4533, create the admin the same way, then:

Set-Location "$HOME\docker_volumes\navidrome"
docker compose logs -f navidrome

Mac (Terminal)#

Same as Linux. Open http://localhost:4533, create the admin, then run docker compose logs -f navidrome in the project folder.

The docs give these first-scan times:

Check it worked. You are logged in, the sidebar shows Albums and Artists, and albums appear as the scan runs. Open one and press play. You can listen before the scan ends.

Tip: An empty library after the scan is almost always a permissions problem. The log says permission denied. See Troubleshooting.

Step 4: Connect a Subsonic app#

Any Subsonic or OpenSubsonic app can connect: add a server with the address, your username and your password. First find the address of the machine that runs Docker.

Linux#

hostname -I

Use the first address: http://<that-address>:4533.

Windows (PowerShell)#

Get-NetIPAddress -AddressFamily IPv4 | Where-Object { $_.IPAddress -notlike '169.254*' -and $_.IPAddress -ne '127.0.0.1' } | Select-Object IPAddress, InterfaceAlias

Windows Defender Firewall may block other devices; the Navidrome docs name this for Windows installs. To allow your private network only, run this as administrator:

New-NetFirewallRule -DisplayName "Navidrome" -Direction Inbound -Protocol TCP -LocalPort 4533 -Action Allow -Profile Private

Mac (Terminal)#

ipconfig getifaddr en0

en0 is usually Wi-Fi on a laptop; if it prints nothing, try en1.

These apps are on the project's apps page (read 5 November 2026). We did not test them.

Check it worked. The app loads your albums and plays a track. If it cannot connect, check the address, the port and the firewall, in that order.

Tip: Make a non-admin user for each person or app (Settings > Users in the web page), or use docker compose run --rm navidrome user create --username <name>.

Step 5: Listen away from home with a VPN#

Do not open port 4533 on your router. The docs ask for a reverse proxy with HTTPS if Navidrome faces the internet. A VPN is simpler: your phone joins your home network and Navidrome never faces the internet.

• WireGuard with wg-easy: your own VPN server; one UDP port is forwarded. See wg-easy with Docker.
• Tailscale: a managed VPN with no router changes. See how we use it in Ollama with Tailscale.

The VPN steps are in those guides. The only Navidrome part is the address: with the VPN on, use the home address from Step 4 in your app. Test from a laptop with the VPN on:

Linux#

curl -s -o /dev/null -w "%{http_code}\n" http://<home-address>:4533/ping

Windows (PowerShell)#

curl.exe -s -o NUL -w "%{http_code}\n" http://<home-address>:4533/ping

Mac (Terminal)#

Same command as Linux.

Check it worked. The test prints 200. On your phone with Wi-Fi off and the VPN on, the app plays a track. With the VPN off it cannot connect. That is correct: nothing is open to the internet.

Tip: Lossless files use a lot of mobile data. Navidrome can transcode on the fly, set per user or per player. Choose a lower quality in your app for the road.

Put it behind HTTPS (with or without Traefik)#

This part is optional. Use it for https://music.<your-domain>. It needs a domain with a DNS record to the server. Local-only users can skip it.

With Traefik#

On a server that already runs Traefik v3 with the Docker provider, add labels and drop the host port.

This assumes an external Docker network called proxy and an entrypoint called https; use your own names. Create the network once:

docker network create proxy

Replace docker-compose.yml with this file (Step 2's settings plus labels and the network):

services:
  navidrome:
    image: navidrome/navidrome:0.64.2
    container_name: navidrome
    restart: unless-stopped
    user: "${APP_UID}:${APP_GID}"
    environment:
      ND_ENABLEINSIGHTSCOLLECTOR: "false"
      ND_BACKUP_PATH: /backup
      ND_BACKUP_SCHEDULE: "0 3 * * *"
      ND_BACKUP_COUNT: "7"
    volumes:
      - "./data:/data"
      - "./backups:/backup"
      - "${MUSIC_DIR}:/music:ro"
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.navidrome.rule=Host(`music.<your-domain>`)"
      - "traefik.http.routers.navidrome.entrypoints=https"
      - "traefik.http.routers.navidrome.tls=true"
      - "traefik.http.services.navidrome.loadbalancer.server.port=4533"

networks:
  proxy:
    external: true

Run docker compose up -d. In your apps, use https://music.<your-domain>. You do not need the BaseUrl setting for a name of its own; it is for a path such as /music.

Check it worked. curl -I https://music.<your-domain>/ returns an HTTP status line over HTTPS and the page opens with a valid certificate.

Without Traefik: Caddy#

Choose this if you have no Traefik. Caddy gets and renews its own certificates.

Caddy reaches Navidrome by container name on the shared proxy network, so Navidrome needs no host port. Use the Traefik file above without its labels: lines. Then create Caddy; we mount the folder conf, not a single file, as Caddy's Docker docs advise:

docker network create proxy
mkdir -p ~/docker_volumes/caddy/{conf,data,config}
cd ~/docker_volumes/caddy

On Windows PowerShell use New-Item -ItemType Directory -Force "$HOME\docker_volumes\caddy\conf","$HOME\docker_volumes\caddy\data","$HOME\docker_volumes\caddy\config". Save as docker-compose.yml there (caddy:2.11.8 was the newest image tag on Docker Hub on 5 November 2026):

services:
  caddy:
    image: caddy:2.11.8
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80/tcp"
      - "443:443/tcp"
      - "443:443/udp"
    volumes:
      - ./conf:/etc/caddy
      - ./data:/data
      - ./config:/config
    networks:
      - proxy

networks:
  proxy:
    external: true

Save as conf/Caddyfile. For a public domain:

music.example.com {
    reverse_proxy navidrome:4533
}

For a home-only name:

music.home.arpa {
    tls internal
    reverse_proxy navidrome:4533
}

Start both stacks with docker compose up -d in ~/docker_volumes/caddy and ~/docker_volumes/navidrome. For tls internal, trust Caddy's root certificate on each device; Caddy as a reverse proxy has the Linux, Windows and Mac commands.

Check it worked. curl -I https://music.example.com/ returns an HTTP status line over HTTPS. For a home-only name the browser shows a padlock once the root is trusted.

Tip: A certificate error usually means the Caddyfile name differs from the DNS record, or ports 80 and 443 do not reach Caddy.

Security and testing#

Navidrome is a login page that holds your listening history. These controls matter most.

Quick tests after each change:

cd ~/docker_volumes/navidrome
docker compose ps
docker compose logs --tail=100 navidrome
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:4533/ping

On Windows run the same lines in PowerShell, with curl.exe for the last one.

What leaves your machine: with the usage report off (Step 2), the docs still list outside integrations that are on by default: Deezer and ListenBrainz lookups (Last.fm needs your own key) and the login screen's background image. ND_ENABLEEXTERNALSERVICES: "false" switches all of them off, the usage report included.

What your library needs#

Navidrome sorts music by tags, not by folder names. The docs say each file should have Title, Artist, Album, Album Artist and Track Number, and all tracks of an album must share the same Album and Album Artist.

Navidrome has no tag editor, no upload and no folder browsing, on purpose. Copy files in with your normal file tools.

Common mistakes#

These come from the official docs, the FAQ, the issue tracker and common AI assistant answers.

Tip: Look every setting up on the official configuration options page. Since 0.64.0 Navidrome warns in the log about options it does not know, so a typo shows up there.

Tip: Keep the music mount read-only. Even a bug cannot change or delete your files through it.

Tip: Test with one small folder of albums first. It scans in under a minute, so you learn quickly whether permissions and tags are right.

Troubleshooting#

For the Mac error, or a Windows database error in Step 2, use a named volume for the data. Change the volume lines and add a volumes: block:

    volumes:
      - "navidrome_data:/data"
      - "./backups:/backup"
      - "${MUSIC_DIR}:/music:ro"

volumes:
  navidrome_data:

Then docker compose down and docker compose up -d. The data now lives in Docker's storage, so rely on the nightly backups for copies.

Diagnostics to run first:

cd ~/docker_volumes/navidrome
docker compose ps
docker compose logs --tail=200 navidrome
docker inspect navidrome --format "{{.Config.Image}}"
docker stats navidrome --no-stream

Known bugs (open, November 2026)#

• Issue #5536: the Mac disk I/O error above. Use a Docker volume.
• Issue #4338: a non-root container fails with mkdir /data/cache/images: permission denied when a tmpfs or volume for the cache is owned by root. Our suggestion: keep the cache inside ./data.

Updates and backups#

Update. Read the release notes, back up, change the tag in docker-compose.yml, then:

cd ~/docker_volumes/navidrome
docker compose pull
docker compose up -d
docker compose logs --tail=100 navidrome

What to back up. Navidrome's own backup saves only the database (users, play counts, playlists), not your music or config, say the docs. The script below copies the data and backup folders; your music needs your normal backup. For encrypted volume backups see restic with Docker.

Linux#

cd ~/docker_volumes/navidrome
docker compose stop navidrome
mkdir -p archive
tar -czf "archive/navidrome-$(date +%F).tar.gz" data backups .env
chmod 600 archive/navidrome-*.tar.gz
docker compose start navidrome

For 03:00 every day, add a crontab line that runs these commands.

Windows (PowerShell)#

Set-Location "$HOME\docker_volumes\navidrome"
docker compose stop navidrome
New-Item -ItemType Directory -Force archive | Out-Null
Compress-Archive -Path data,backups,.env -DestinationPath "archive\navidrome-$(Get-Date -Format yyyy-MM-dd).zip" -Force
docker compose start navidrome

For 03:00 daily, save those lines as a .ps1 file and add a Task Scheduler task with a daily trigger and the action powershell.exe -File <path-to-script>.

Mac (Terminal)#

Same commands as Linux; schedule with crontab or a launchd job.

Restore test. Unpack an archive into a new empty folder, never over the live one:

mkdir -p /tmp/navidrome-restore && tar -xzf archive/navidrome-<date>.tar.gz -C /tmp/navidrome-restore
ls /tmp/navidrome-restore/data

To restore a database backup, the docs say stop the server first:

docker compose stop navidrome
docker compose run --rm navidrome backup restore --backup-file navidrome_backup_<date>_<time>.db
docker compose start navidrome

Performance and resources#

The docs give no memory or CPU figures, so we give none. They say Navidrome has "very low resource usage" and runs on a Raspberry Pi Zero. Measure your own machine:

• Live use: docker stats navidrome shows CPU and memory.
• Scans: the first scan is the heavy part (table in Step 3). The watcher waits 5 seconds after a change (Scanner.WatcherWait); scheduled scans are off by default.
• Caches: the image cache is 100 MB by default (ImageCacheSize).
• Transcoding: the image includes ffmpeg, so converting on the fly (Opus too) needs no install. It uses CPU only when a user or player is set to transcode.

FAQ#

Is Navidrome free to use? Yes, under GPL-3.0. Only the managed hosting providers named in the docs charge, for the hosting.

Does it need a GPU? No. The docs do not mention one.

Can I use my Jellyfin music app? Since 0.64.0 there is an experimental Jellyfin API, off by default (ND_JELLYFIN_ENABLED=true). The docs name Finamp, Jellify and Feishin as tested. For video as well, see our Jellyfin guide.

Can I run it on Windows or macOS without Docker? Yes: the docs describe a Windows MSI installer and a macOS binary with a navidrome service command.

Does it send data to the project? By default it sends an anonymous usage report (no emails, IP addresses or usernames, says the docs). Our Compose file turns it off.

Sources#

• Navidrome release v0.64.2 and v0.64.0, Dockerfile, LICENSE and logo - read November 2026
• Navidrome docs: Docker, Getting started, Overview, Configuration options, Security, Backup, CLI, Data collection, FAQ, Tagging, Jellyfin API, Windows and macOS installs, and the apps page - read November 2026
• Docker Hub: navidrome/navidrome (tag 0.64.2) and caddy (tag 2.11.8), checked 5 November 2026; Caddy TLS directive
• GitHub issues #3406, #4338, #5491, #5536 and #6171 - read November 2026

Checked against the official docs on 2026-11-05.