# Navidrome Music Server

> Navidrome music server with Subsonic API compatibility.

- Category: Media & Entertainment
- Difficulty: beginner
- Components: navidrome
- Tags: navidrome, music, streaming, subsonic, audio
- Source: https://docker.recipes/media/navidrome-music-server

## Overview

Navidrome is a modern, self-hosted music streaming server that provides a web-based interface and Subsonic API compatibility for accessing your personal music collection from anywhere. Originally developed as a lightweight alternative to more resource-intensive music servers, Navidrome focuses on simplicity, performance, and cross-platform compatibility while supporting a wide ecosystem of mobile and desktop music clients through its Subsonic API implementation.

This Docker deployment creates a complete personal music streaming solution that automatically scans and indexes your music library, generates album artwork, and provides both a responsive web interface and API endpoints for third-party applications. The container runs with proper user permissions to access your music files safely while maintaining persistent configuration and database storage separate from your media files.

This setup is ideal for music enthusiasts who want to stream their personal collection across devices, families sharing a music library, or anyone seeking to reduce dependence on commercial streaming services. The Subsonic API compatibility means you can use dozens of existing mobile apps and desktop clients, making Navidrome a drop-in replacement for commercial services while keeping full control over your music data and streaming quality.

## Features

- Subsonic and OpenSubsonic API compatibility for use with dozens of existing mobile and desktop music clients
- Automatic music library scanning with configurable intervals and real-time file system watching
- Built-in audio transcoding with support for multiple codecs and bitrate conversion on-the-fly
- Smart playlists and favorites with support for importing existing M3U playlists
- Multi-user support with individual libraries, playlists, and listening statistics
- Last.fm scrobbling integration for tracking listening habits across platforms
- Responsive web interface with support for offline playback and queue management
- ReplayGain support for consistent volume levels across tracks and albums

## Use cases

- Personal music streaming server for accessing large FLAC collections from mobile devices
- Family music sharing with separate user accounts and parental controls
- Audiophile setups requiring lossless streaming with on-demand transcoding for mobile
- Home lab environments consolidating media services with existing NAS storage
- Small office background music systems with centralized library management
- Travel and remote access to personal music collections via VPN or reverse proxy
- Migration path from commercial streaming services while maintaining mobile app compatibility

## Prerequisites

- Docker and Docker Compose installed with at least 512MB available RAM
- Music library organized in a directory structure accessible to Docker containers
- Port 4533 available for the Navidrome web interface and API access
- Basic understanding of file permissions and user/group IDs for media access
- Network access configuration if planning to use external Subsonic clients
- Sufficient disk space for transcoding cache and database storage

## docker-compose.yml

```yaml
services:
  navidrome:
    image: deluan/navidrome:latest
    container_name: navidrome
    restart: unless-stopped
    user: "${PUID:-1000}:${PGID:-1000}"
    ports:
      - "${NAVIDROME_PORT:-4533}:4533"
    environment:
      ND_SCANSCHEDULE: ${SCAN_SCHEDULE:-1h}
      ND_LOGLEVEL: info
      ND_SESSIONTIMEOUT: 24h
      ND_BASEURL: ""
    volumes:
      - navidrome_data:/data
      - ${MUSIC_PATH:-./music}:/music:ro
    networks:
      - media-network

volumes:
  navidrome_data:

networks:
  media-network:
    driver: bridge
```

## .env

```bash
# Navidrome Music Server
NAVIDROME_PORT=4533
PUID=1000
PGID=1000
MUSIC_PATH=./music
SCAN_SCHEDULE=1h
```

## Usage notes

- Navidrome at http://localhost:4533
- Create admin account on first run
- Use any Subsonic-compatible client
- Supports transcoding on the fly

## Troubleshooting

- Music files not appearing in library: Check PUID/PGID environment variables match your music directory ownership and verify the music path mount is correct
- Transcoding failures or poor audio quality: Ensure the container has sufficient CPU resources and check ND_LOGLEVEL for FFmpeg errors in container logs
- Subsonic client connection errors: Verify the client is using the correct server URL format (http://server:4533) and that API compatibility is enabled in Navidrome settings
- Slow library scanning on large collections: Adjust ND_SCANSCHEDULE to a longer interval and consider using SSD storage for the database volume
- Web interface not accessible: Check that NAVIDROME_PORT environment variable matches your desired port and verify firewall rules allow access to port 4533
- Database corruption after container restart: Ensure navidrome_data volume has proper write permissions and avoid force-stopping the container during scan operations

