Sonarr and the Problem of Keeping a Library True
Sonarr is often described as a PVR for Usenet and BitTorrent users. That description is accurate, but it hides the harder problem the project actually solves. This series examines Sonarr as a policy-driven reconciliation system: how it keeps a desired episodic library aligned with release feeds, download clients, and files that it does not control. The practical value of that view is simple: it lets a reader trace an episode from intention to library file, and understand why Sonarr sometimes acts, sometimes waits, and sometimes refuses to act.
The distinction matters because “downloaded” is not the same as “correctly added to the library.” A release may be visible but belong to another show. A title may identify a season but not the intended episode. A file may be complete but still be in a path Sonarr cannot safely interpret. Even a good release can be the wrong choice if it violates the quality or monitoring policy attached to the series. Sonarr's central challenge is therefore not the existence of a download button. It is deciding when an external observation is strong enough to change durable library state.
A PVR is not the same as a download queue
A basic download queue answers a narrow question: what should be transferred next? Sonarr must answer a longer chain of questions. Which shows belong in the library? Which episodes are wanted? Which episodes already have files? If several releases are available, which one satisfies the reader's quality expectations? After a transfer completes, which local file represents which episode, and should it replace an existing file?
The repository's own feature description reflects this wider responsibility. Sonarr monitors feeds for new episodes, grabs, sorts, and renames them, and can upgrade files already downloaded when a better quality becomes available. It also describes scanning an existing library for missing episodes, handling failed downloads, supporting manual search, and integrating with external download clients and media servers. These are not unrelated conveniences. They are stages in maintaining a collection whose contents change over time.
Consider a continuing show with one missing episode. Sonarr does not begin with a file. It begins with a record of the show and its episodes, a monitoring choice that says the episode matters, and a quality policy that describes what would be acceptable. It then observes release candidates from outside systems. Its job is to compare those candidates with the stored intent before sending anything elsewhere.
That comparison also defines Sonarr's boundary. Sonarr can choose a release, submit it to a configured client, observe the resulting item, and import a verified file. It cannot make an indexer publish a release, make a download client complete it, or make an inaccessible path readable. The application is an intermediary that coordinates these systems; it is not the owner of all of them.
The library has a desired state and an observed state
The most useful mental model is to separate two kinds of information.
The desired state is what the library is meant to contain. In Sonarr, a series record carries identity and metadata such as titles, external identifiers, status, dates, type, path, tags, monitoring, and a quality-profile assignment. Episodes belong to the series and carry season and episode numbers, air dates, monitoring, and a relationship to an optional episode file. Monitoring is especially important: it expresses whether Sonarr should pursue an episode at all, rather than merely whether the episode exists somewhere in the world.
The observed state is what Sonarr can currently see. A release candidate has a title, size, publication date, protocol, indexer, and links. A download-client item has a status, an identifier, remaining size, output path, and capabilities such as whether its files can be moved or the item can be removed. An episode file records facts about media already in the library, including its path, size, quality, languages, and release provenance.
Those states are related, but they are not interchangeable. A release candidate is evidence about a possible future file. It is not yet a library file. A downloader's “completed” status is evidence that an external process finished; it is not by itself proof that the files can be mapped to the right episodes. A file on disk is an observation that still needs to be associated with the library's canonical records.
The durable model is what makes repeated reconciliation possible. If Sonarr only reacted to feed entries in memory, it could not reliably distinguish a missing episode from one already imported, or an upgrade from a duplicate. By persisting series, episodes, files, profiles, commands, and history, it can compare a new observation with what it already knows and choose a different action when the context has changed.
This diagram is deliberately not a component inventory. It shows why the components need one another. Metadata helps establish the desired state. Indexers provide candidate observations. A download client performs work outside Sonarr. The filesystem later supplies another observation. Verification turns that observation into a canonical file, and history and events give later decisions memory.
The loop also explains why a reader's settings matter. Monitoring is not a cosmetic label; it determines whether an episode is in scope. Quality preferences are not only display metadata; they influence whether an existing file is good enough or whether a new release can replace it. The repository models these choices alongside the series and episode records so that automation has a stable reference point.
Three objects that should never be confused
A useful way to test the model is to distinguish a candidate, a decision, and a library file.
A candidate is an external possibility. It may come from an RSS feed or an explicit search. Its title and metadata must still be parsed and mapped to a known series and episode. A candidate can be unknown, ambiguous, too old, too large, or outside the monitoring and quality policy. Its existence says only that an outside source reported something.
A decision is Sonarr's reasoned response to that candidate. The decision engine combines parsed release information with the stored series and episode context. It can produce an acceptance, a rejection, or a temporary outcome such as waiting for a better candidate. This is where policy becomes action: a candidate may be technically recognizable but still not wanted, or it may be wanted but temporarily held back.
A library file is a durable result. It has a canonical relationship to episode records and a path that the rest of the media library can use. Getting there requires more than the candidate's title. Sonarr must observe the external download, determine that the path is usable, interpret the local files, and import the approved result. The file then becomes part of the state against which future releases are judged.
Confusing these objects produces misleading diagnoses. “The release was found” does not mean “Sonarr should download it.” “The download completed” does not mean “the episode was imported.” “The file exists” does not mean “the file is correctly mapped.” Each statement belongs to a different boundary in the loop.
This separation is also why the project supports both automatic and manual paths. Automatic behavior is valuable when identity and policy are clear. Manual search and manual import remain useful when the available evidence is insufficient or when a reader wants to override the ordinary path. Human involvement is not a failure of the model; it is one of the model's explicit outcomes when the system cannot safely infer intent.
Automation must be selective to be trustworthy
The central tension in Sonarr is between coverage and correctness. A system that never acts is not useful. A system that acts on every plausible release will eventually attach the wrong content to the wrong episode, rename or move files incorrectly, or replace a file that already satisfies the reader's intent.
Sonarr addresses that tension by making state and transitions explicit. The application schedules recurring work, puts commands into a priority-aware queue, prevents duplicate queued or started commands, and coordinates tasks that should not compete for disk or exclusive execution. It publishes events as work changes state, which allows other parts of the application and the user-facing API to observe progress without making every concern part of one giant procedure.
That architecture gives the loop memory and timing. A metadata refresh can lead to a scan. A scan can reveal missing or newly relevant episodes. A search can produce candidates that are evaluated under current policy. A later command can revisit work that was delayed or interrupted. The exact transition may be asynchronous, but the important point is that Sonarr does not treat each operation as an isolated request with no history.
The same design makes limits visible. The repository supports an authenticated API, versioned API surfaces, and live messaging, so users and automation can inspect and control parts of the process. But an API endpoint does not remove the underlying uncertainty. It can expose a queue or command state; it cannot guarantee that an external indexer has complete data or that a downloader's path is available to the running service.
Sonarr is therefore best judged by the quality of the boundary decisions it makes. It should act when the desired episode, the candidate identity, and the policy line up. It should wait when a better answer may arrive and the current candidate is not urgent. It should reject or request manual help when the evidence does not support a safe mapping. History and events matter because they let the application make those decisions again without forgetting what happened before.
The phrase “keeping a library true” does not mean that Sonarr can establish an abstract, universal truth about media. It means something narrower and more useful: keeping the durable library records consistent with the reader's stated intent, the evidence Sonarr can observe, and the policies that govern change. That is why Sonarr is more than a downloader, and why understanding its relationships matters more than memorizing its list of integrations.