Getting Started

Already installed? Play us a song, Navidrome!

This guide walks you through your first session with Navidrome, from verifying your installation to playing your first song.

Before You Begin

Make sure you’ve completed the installation for your platform. Verify these items before proceeding:

Step 1: Verify Navidrome is Running

Before creating your admin user, confirm Navidrome started successfully.

Check the logs for a successful startup message:

docker logs navidrome

sudo journalctl -u navidrome -f

Check the log file in your Navidrome installation folder, or use Event Viewer for service logs.

cat /opt/navidrome/navidrome.log

Or check the path you specified in your LaunchAgent plist.

What success looks like: You should see log entries showing Navidrome starting up and beginning to scan your music folder. Look for messages like:

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

If you see errors about missing folders or permission denied, see Troubleshooting below.

Step 2: Create Your Admin User

Open your browser and navigate to http://localhost:4533 (or your custom address/port).

You should see the admin user creation screen:

Fill in your desired username and password, confirm the password, and click “Create Admin”.

What success looks like: After clicking the button, you’ll be logged in and see the Navidrome interface. The sidebar will show menu items like “Albums”, “Artists”, “Playlists”, etc.

Step 3: Wait for Your Music to Appear

Navidrome scans your music folder in the background. This takes time — the duration depends on your library size:

Library Size Approximate Scan Time
< 1,000 songs Under 1 minute
1,000 - 10,000 songs 1-5 minutes
10,000 - 50,000 songs 5-15 minutes
50,000+ songs 15+ minutes

What success looks like: Albums and artists will gradually appear in the interface. You can monitor progress in the logs — look for messages showing files being processed.

Step 4: Play Your First Song

Once some music appears:

  1. Click on “Albums” in the sidebar
  2. Click on any album cover
  3. Click the play button on any track

Congratulations! You’re now streaming your own music with Navidrome. 🎉

Troubleshooting

Music Not Appearing

Check scan progress in the logs. If you see ongoing scan activity, just wait — large libraries take time.

Verify your music folder path:

  • Ensure the path in your configuration matches where your music files actually are
  • Check that paths are case-sensitive on Linux/macOS
  • For Docker: verify your volume mount is correct (e.g., -v /path/to/music:/music:ro)

Check file formats. Navidrome supports MP3, FLAC, AAC, OGG, OPUS, WMA, APE, WavPack, and more. Files must have proper audio metadata (tags) to appear correctly.

Permission Problems

The Navidrome process must have read access to your music folder.

Ensure the user directive matches the owner of your music folder:

user: 1000:1000  # Should match: ls -n /path/to/music

# Check current permissions
ls -la /path/to/music

# If needed, ensure the navidrome user can read:
sudo chmod -R o+rX /path/to/music
# Or add the navidrome user to the appropriate group

Right-click your music folder → Properties → Security tab. Ensure the service account has Read permissions.

# Check permissions
ls -la /path/to/music

# Grant read access if needed
chmod -R o+rX /path/to/music

If using Full Disk Access, ensure Terminal or the Navidrome process has the permission in System Settings → Privacy & Security.

Cannot Access Navidrome in Browser

  1. Verify the service is running (see Step 1 above)
  2. Check you’re using the correct URL:
    • Default: http://localhost:4533
    • If accessing remotely, use your server’s IP address
    • If you configured a custom port, use that instead
  3. Check firewall settings — port 4533 (or your custom port) must be open
  4. For Docker: ensure the port mapping is correct (-p 4533:4533)

Playlists Not Importing

Navidrome imports .m3u playlists from your music folder, but only after an admin user exists. If playlists aren’t appearing:

  1. Make sure you’ve created the admin user first
  2. Update the playlist file timestamps to trigger reimport: 
    touch /path/to/music/*.m3u
  3. Wait for the next scan cycle, or trigger a manual scan from the UI

Platform-Specific Tips

  • User permissions: The user: 1000:1000 in docker-compose should match your music folder owner. Check with ls -n /path/to/music
  • Volume paths: Use absolute paths, not relative ones
  • Logs: Use docker logs -f navidrome to follow logs in real-time
  • Restart: docker-compose restart navidrome to apply config changes
  • Service management: Use systemctl status navidrome to check service health
  • SELinux/AppArmor: These may block access to music folders. Check with ausearch -m avc or system logs
  • Socket permissions: If using Unix sockets for reverse proxy, ensure correct permissions
  • Service account: The service runs as Local System by default. Change to your user account if you need access to network drives
  • Path format: Use Windows paths in navidrome.toml (e.g., MusicFolder = "C:\\Music")
  • Firewall: Windows Defender may block the port — add an exception if needed
  • Quarantine errors: If you see “navidrome is damaged”, run: sudo xattr -d com.apple.quarantine /path/to/navidrome
  • Full Disk Access: May be required for some music folder locations
  • LaunchAgent logs: Check the paths in your plist file match reality

Next Steps

Now that Navidrome is running, explore these features:

Still having trouble? Check the full documentation or reach out to the community for help.

Externalized Authentication Quick Start

Quick Start guide


Last modified January 12, 2026: Update daily deploy workflow and remove Netlify status from README (d451eaf)