Navidrome: a self-hosted music server that speaks the Subsonic API

What Navidrome is for, and who ends up running it

Navidrome is a web-based music collection server and streamer. The README frames the pitch bluntly: it is for people tired of paying for music subscriptions and not finding what they like. That framing tells you the target user. You already have the files. You have probably spent years tagging them, splitting box sets, and fixing compilation albums so the artist field is not a mess. Navidrome's job is to index that library and serve it over HTTP, not to build a library for you.

The feature list is written for that person. It handles very large music collections, reads the metadata you already curated, and gives explicit support for compilations (Various Artists albums) and box sets (multi-disc albums). Those two cases are where naive servers fall apart: they collapse a Various Artists record into one artist, or they flatten disc 2 into disc 1. Multi-user support is also first class, with each user keeping their own play counts, playlists and favourites. If you are the only listener, that matters less. If a household shares the server, it matters a lot.

Who it is not for: anyone expecting a media centre. There is no video, no live TV, no automatic acquisition of missing albums. The README describes a music server, and the repository layout backs that up. The scanner/ directory handles library scanning, server/ holds the HTTP surface, ui/ is the web client. Nothing in the top-level entries suggests a general-purpose media platform.

How the server works: scanner, SQLite, and the Subsonic surface

The architecture is visible from the repository layout and go.mod. A scanner package walks your library and reads tags; a persistence layer stores the result; a server package exposes HTTP endpoints. The README states that Navidrome automatically monitors your library for changes, importing new files and reloading new metadata. So the data flow is: files on disk, tag extraction, database rows, then API responses.

Tag reading is not incidental here. go.mod carries a replace directive pointing go.senan.xyz/taglib at a fork, commented as a fork to implement raw tags support. That is a deliberate dependency choice rather than a stock library, and it explains why the project can read the metadata it advertises. The database is SQLite: go.mod requires github.com/mattn/go-sqlite3, and the Makefile sets build tags netgo,sqlite_fts5, which turns on SQLite's full-text search extension. That is the mechanism behind searching a large collection without a separate search service.

On the HTTP side, go.mod includes go-chi/chi/v5 for routing, go-chi/httprate for rate limiting, go-chi/jwtauth/v5 for token authentication, and gorilla/websocket. Authentication is token-based, not session-cookie-only, which is what lets third-party clients log in with a username and password and then hold a token. The compatibility story rests on the Subsonic API, and the README links a dedicated Subsonic API compatibility page in the docs. That page, not the README, is where you check whether a specific endpoint your client needs is implemented.

One more signal worth reading: the Makefile exports ND_ENABLEINSIGHTSCOLLECTOR=false globally. The project disables its own insights collector in builds produced by that Makefile. If you build from source using those targets, you inherit that setting.

Installing Navidrome and playing the first track

The README does not inline installation steps. It states: see instructions on the project's website, at the installation page, which splits into Docker, pre-built binaries, and build from source. The Docker image referenced in the README badges is deluan/navidrome, and the Makefile's default DOCKER_TAG is deluan/navidrome:develop. The README also warns that the master branch may be unstable or broken and that you should use releases rather than master for a stable set of binaries. Take that warning literally.

The repository's own Dockerfile builds the image for multiple platforms, including linux/amd64, linux/arm64, linux/arm/v6, linux/arm/v7 and linux/riscv64, which is why the README can claim Raspberry Pi binaries. For a first run, the Docker route is the shortest path, but the exact volume paths and environment variable names belong to the website's Docker page, not to this README. What the README does confirm is the image name, deluan/navidrome.

After pulling the image, you point the container at a music directory and a data directory, then open the web interface in a browser. The README does not document the port inline; the related search phrase "navidrome port" exists precisely because people look it up, and the answer lives in the configuration docs on the website. Do not guess it from the README, because the README does not state it.

For development rather than deployment, the Makefile is explicit. There is a setup target described as run first, which installs dependencies, and a dev target that starts Navidrome with hot reload for both frontend and backend. The dev target runs npx foreman with Procfile.dev on port 4533. That is a development port, not a production recommendation, and the Makefile's server target runs the backend through go tool reflex with reflex.conf. The Makefile also notes that the go build tags include netgo and sqlite_fts5. If you build by hand rather than through make, you need those tags or you lose full-text search.

The Go version is pinned in go.mod at go 1.27, and the Node version comes from .nvmrc. Building from source therefore means matching both toolchains. That is a real cost, and it is the reason most people should use the Docker image or a pre-built binary instead.

Where Navidrome stops: tagging, transcoding and the client question

The most common disappointment with Navidrome is not a bug. It is a mismatch of expectations. The README says it reads and uses your beautifully curated metadata. The word curated is doing work there. If your files have inconsistent artist strings, missing album artist tags, or track numbers that reset per disc without disc tags, the server will faithfully index the mess. Navidrome is not a tagger and does not claim to be. Tools that rewrite your tags are a different category of software.

Transcoding is supported and can be set per user and per player, with Opus encoding supported according to the README. That is useful when a client on a slow connection cannot handle a large FLAC file. It is also a source of confusion, because per-player settings mean the same track can sound different on two devices, and a misconfigured transcoder can silently downsample everything. The README does not document rollback of a bad transcoding profile, so treat profile changes as something to test on one player first.

Lyrics support is broad on paper: sidecar .ttml, .yaml/.yml Lyricsfile, .elrc, .lrc, .srt and .txt files, plus embedded TTML, Enhanced LRC, LRC, SRT and plain-text tags, resolved through a lyricspriority setting. Breadth here means configuration. If you have a mix of formats, you have to decide which wins, and the README names the key but not the ordering rules.

The other boundary is the client. Navidrome is compatible with Subsonic, Madsonic and Airsonic clients, and the README links a list of apps. That is a strength and a constraint at the same time: the server ships a web interface, but on a phone you are using someone else's app, with its own bugs, its own Subsonic coverage, and its own release cadence. The search data around Android, iOS and specific clients reflects exactly this. If you want one vendor to be responsible for the whole experience, Navidrome is the wrong shape of project.

Navidrome against Jellyfin and Plexamp

The comparison people actually search for is Jellyfin versus Navidrome, and the difference in approach is structural, not cosmetic. Jellyfin is a media server that covers video, television, music and more, with its own client apps and its own API. Navidrome does music only, and it exposes a Subsonic-compatible API rather than a proprietary one. That single decision cascades: Navidrome inherits a large installed base of existing clients it did not have to write, and in exchange it inherits the Subsonic API's age and its rough edges. If your library is music and nothing else, the narrower server is simpler to run. If you also want films, you are not choosing between the two at all.

Plexamp is a different proposition again. It is a first-party client experience tied to a commercial ecosystem, and the comparison is really about control. Navidrome is GPL-3.0, self-hosted, and does not require an account with a third party. Plexamp is polished and integrated but not something you run yourself. Someone who values a single coherent app over self-hosting will not be persuaded by Navidrome's feature list, and they should not be.

A fair summary: Navidrome competes on library handling and API compatibility, not on breadth. Its claims about large collections, compilations and box sets are the ones to test against your own files, because that is where the design effort is concentrated.

Maintenance, releases and the GPL-3.0 licence

The repository is not archived, and the last push was on 2026-07-11, which coincides with the v0.63.2 release. Recent releases are close together: v0.63.0 on 2026-07-08, v0.63.1 on 2026-07-09, v0.63.2 on 2026-07-11. That pattern suggests a project that ships fixes quickly after a minor release, and it means upgrading is a normal, expected operation rather than a rare event.

The upgrade cost depends on how you installed it. With Docker, upgrading means pulling a newer tag and restarting the container; the README points to the Docker installation page for specifics. With pre-built binaries, you replace the binary. With a source build, you are tracking Go 1.27, the Node version in .nvmrc, and the build tags in the Makefile. The source path is the one that decays fastest if you do not keep the toolchain current.

Database migrations are handled in-process: go.mod requires github.com/pressly/goose/v3, a migration library. That means a version upgrade can alter your SQLite schema on first start. Back up the data directory before upgrading across minor versions. This is not stated in the README, but it follows from the presence of a migration tool and from the fact that your library database is the state you cannot recreate by re-downloading anything.

Licence: Navidrome is GPL-3.0. For self-hosting, that is uncomplicated. If you intend to modify and distribute it, or to offer it as a service to others, the copyleft terms apply and you should read the LICENSE file rather than rely on a summary. Nothing here is legal advice.

Editorial conclusion

Adopt Navidrome if you already own a curated music library, want multi-user play counts and playlists, and prefer a server that stays out of the way of your existing Subsonic clients. Do not adopt it if you need video, automatic metadata correction of badly tagged files, or a client you do not have to choose yourself. Verify first that your tags are consistent, that your chosen client supports the Subsonic endpoints you rely on, and that your deployment path (Docker image or pre-built binary) matches your platform, since the README sends you to the website for installation rather than documenting it inline.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes