Instruction 09-radarr-naming-and-movie-library-hygiene: Reading

Radarr naming has two related but separate layers: the movie folder and the movie file. A folder identifies the logical movie managed by Radarr, while a file identifies a particular media asset currently satisfying that movie. A durable policy usually gives the folder a human-readable title, the release year, and, where supported by the surrounding tools, a stable external identifier. A conceptual folder could therefore resemble Arrival (2016) [tmdb-329865]. The year distinguishes many remakes, while the identifier resolves cases involving alternate titles, localization, punctuation, or two movies released in the same year. The media file may additionally carry quality and edition information because those properties describe the asset rather than merely the movie record.

Consistency matters more than decorative complexity. Every added token creates another dependency on metadata quality and tool compatibility. Before adopting a template, confirm that the installed Radarr version recognizes every token, inspect the example shown in the naming settings, and verify that media players, backup tools, subtitle applications, and indexers tolerate the resulting characters. Avoid manually typing identifier text into templates as if it were ordinary metadata; use supported Radarr tokens so each movie receives its own value. Token names and formatting capabilities can change across releases, so the live naming preview is authoritative for the installed instance.

Renaming is not the same as rediscovering metadata. Radarr renames files according to the movie records and media files it already knows. If a file is matched to the wrong movie, a perfectly formatted name can make that incorrect match look legitimate. Resolve unmatched files, duplicate records, incorrect editions, and bad metadata before bulk organization. The safest workflow is inventory, preview, small pilot, verification, and then staged expansion. Record current and proposed paths before making changes. A path mapping is useful for rollback, audit review, and diagnosing applications that retained an old path.

Folder and file changes can affect more than Radarr. A media server may need to rescan paths. Subtitle files can become detached when their base name no longer follows the movie file. Automation scripts may depend on old directories. Hard links remain links to the same inode when renamed on one filesystem, but a workflow that copies across filesystems behaves differently. Symbolic links can become stale when their stored target path changes. Backups may treat a mass rename as a large deletion and addition even when content bytes did not change. These consequences are why this class uses a synthetic library and generates proposals rather than changing a production collection.

A hygiene audit should separate warnings from confirmed faults. A missing year is an ambiguity warning, not proof that a movie is wrong. An unexpected extension may be a legitimate sidecar. A duplicate proposed target is a blocking fault because applying both mappings would overwrite or merge identities. Control characters, trailing spaces, platform-reserved characters, and inconsistent Unicode forms may cause portability problems. Edition labels should be explicit and consistently sourced instead of inferred from arbitrary release text. Quality labels are useful for humans and recovery, but Radarr's database remains the primary authority for upgrade decisions.

A practical naming policy should be deterministic: the same metadata should always produce the same path. It should also be reversible enough that an administrator can identify the movie from the path if the application database is unavailable. Keep folders stable when possible and allow asset-specific information to live in file names. Do not use a naming cleanup as a substitute for backups, metadata correction, permission design, or storage monitoring. Naming is one layer of library integrity, not the entire integrity model.