library-doctor
Docker app from spikey1965's Repository
Library Doctor checks your Plex library against Radarr, Sonarr and what's really on the disk, and tells you what needs fixing: missing files, duplicates (with which copy to keep…
Requirements
Overview
An Analysis tab shows a library score (file integrity, quality, metadata, duplicates, app sync), trends, storage recovered and quality per library.
After installing, open the WebUI, set a password, then add Plex and Radarr/Sonarr in Settings. Settings → Folder check shows whether each app sees your media at the same place as Library Doctor and suggests a mapping if not.
Media path: point it at the share that holds your films and shows (one folder, mounted read-write), for example /mnt/user/data/media.
Readme
View on GitHubLibrary Doctor
A nightly health check for your Plex library. Library Doctor compares what Plex shows with what's really on the disk and what Radarr and Sonarr think they have. Every morning you get one page with everything that needs fixing, and a button to fix most of it.
Beta. Built on the author's own home server and now being tested on others. Please open an issue if something looks wrong.
Try the live demo (made-up library, nothing real is changed) · How it works

What it checks
| Check | What it finds | Needs |
|---|---|---|
| Missing files | Plex, Radarr or Sonarr list a file that isn't on the disk, and season gaps: aired episodes Sonarr wants but never got (Search for these) | Plex + Radarr/Sonarr |
| Duplicates | Two copies of the same film or episode, with which one to keep and why (different Plex editions, like Theatrical and Director's Cut, are never counted as duplicates, and neither are different films with the same title, like The Fly 1958 and 1986: if Plex mixed them up you get Split in Plex instead) | Plex |
| Metadata gaps | "Episode 5" titles Sonarr knows the name of, wrong years, things not in Radarr/Sonarr | Plex + Radarr/Sonarr |
| File health | Broken files, files much shorter than they should be, and the wrong audio language (also checked within 10 minutes of each import) (an English film with only Russian audio, a dubbed season). Replace asks Radarr/Sonarr for a new copy and checks it when it arrives | Plex + Radarr/Sonarr |
| Quality & space | Files far bigger than usual, old .ts/.avi files (Convert to MKV, no re-encoding), episodes much worse than their season, Find a smaller copy, and release groups whose files keep having to be replaced (Block it) | Plex + Radarr/Sonarr |
| Subtitles | Subtitle files that are only adverts, names that no longer match the video, what Bazarr is still looking for | Bazarr |
| Unwatched | What nobody has played in a year, biggest first (never deletes anything) | Tautulli |
| Virus scan | Programs pretending to be films (film.mkv.exe), and ClamAV on every new file | ClamAV (optional) |
| Coming Soon | Agregarr placeholders playing a generic clip instead of the real trailer | Agregarr (optional) |
| App Health | Each app's own warnings (Radarr/Sonarr/Prowlarr health, Bazarr, Tdarr nodes), apps that stop answering, updates (with Update now, or the Docker commands to copy), and indexers that keep failing and never find anything | Radarr/Sonarr (Prowlarr optional) |
| Downloads | Radarr/Sonarr queue problems: finished downloads they won't import (Import button), downloads that are stuck, with the reason from your download client (no seeds, tracker error, slow, usenet failure) and Re-announce / Remove & try another, and leftovers in the download clients' incomplete folder | Radarr/Sonarr (qBittorrent, Transmission, SABnzbd, NZBGet optional) |
| Disk space | Free space now and, after a week of daily readings, how fast it fills and roughly when it's full | — |
Tdarr (Convert with Tdarr) and Sportarr (sports libraries) are optional too. For the nightly summary you can add any of Gotify, Discord, Telegram, ntfy, a webhook or email in Settings → Notifications.
Nothing is deleted without asking
- Library Doctor only reads from your apps until you press a fix button.
- Every clean-up moves files into its own trash (
.library-doctor-trashinside your media folder, same disk, so it's instant). You can put anything back for 7 days (3, 7, 14 or 30 in Settings), then the trash empties itself, but only after a closer look: a file is kept back if the copy that was kept is gone, a replacement hasn't arrived yet, or it would be the only copy. - Suggestions are marked Sure (a tiny broken copy, a leftover temp file) or Check (two good copies, have a look first).
Install (Docker Compose)
- Make a folder, save
compose.yamlin it and change the three lines markedCHANGE:PUIDandPGID: the user and group that own your media (runls -ln /path/to/media; the two numbers after the permissions)TZyour time zone/path/to/mediathe folder that holds your films and shows
- Start it:
docker compose up -d - Open
http://<your-server>:8790and create a password straight away: until one is set, anyone who can reach the page could set it, so don't expose the port to the internet before this. Then add Plex and at least one Radarr or Sonarr under Settings. Press Test on each one, then Save and Scan now.
After that it scans by itself every night at 3am.
Unraid
Library Doctor is in Community Applications: open Apps, search Library Doctor and click Install. Set Media to the share that holds your films and shows (e.g. /mnt/user/data/media); PUID 99 / PGID 100 are Unraid's defaults. Then open the WebUI and set a password.
If it doesn't show up yet (new apps appear after the next Community Applications update), use Docker → Add Container → Template repositories, add https://github.com/spikey1965/unraid-templates, and pick library-doctor.
Mount your media as one folder
Library Doctor needs to see your films and shows inside one mount (for example /mnt/media with movies/ and tv/ inside it), mounted read-write. Clean-up moves files with a rename, which only works within one disk or dataset. If your films and shows are on different disks, mount their common parent folder.
Folder mapping
Your apps may see the same files at different paths (Plex might say /data/movies, Radarr /movies, Library Doctor /media/movies). Settings → Folder check does this for every app at once: it asks each app for a few real files, applies that app's mapping and looks for them under /media, with ✓ or ✗ per app and a Use suggested mapping button when something's off. It runs by itself when you open Settings and after every save. You can also press Detect folders on one app's card, or add a mapping by hand.
Before every scan Library Doctor checks again: if it can't find Plex's or Radarr/Sonarr's files at all, the scan stops with a message instead of reporting your whole library as missing.
Roadmap
No dates, just the order things are likely to happen. Ideas and offers to test are welcome in Issues.
- Planned: Jellyfin and Emby support (being tested first).
- Being considered: Jellyfin and Emby support; music libraries; a Home Assistant card.
Known limitations
This is a beta, so a few things are worth knowing before you start:
- One media mount. Clean-up, Replace and Convert to MKV move files into
.library-doctor-trashwith a rename, which only works within one disk or dataset. If your films and shows are on different disks, scans still work but those fixes can't move files; Library Doctor shows a warning on its main screen when it spots this. - Plex only. Jellyfin and Emby aren't supported yet.
- Tested on TrueNAS so far. Unraid, Synology, Raspberry Pi (ARM) and Docker Desktop haven't been tried by anyone yet. If you run one of those, an issue saying how it went (good or bad) really helps.
- Hardlinks. A file that's also hardlinked elsewhere (typically a torrent that's still seeding) frees no space when it's moved. Library Doctor marks these as Hardlinked, never offers two links to the same file as duplicates, and doesn't count them in the space totals. Replacements made by Radarr itself (Find a smaller copy) can't be checked this way yet.
- Sleeping disks. The scan never reads your video files; it only checks they exist and their size (and reads small subtitle files). On a NAS whose disks spin down, that can still wake them, so pick fewer days under Settings → Automatic scan (once a week is fine).
- Radarr/Sonarr v3 API. It talks to the current Radarr and Sonarr (including Sonarr 5). Very old versions may not work.
- English and the author's library. The checks were tuned on one real library of about 7,500 films and episodes. If a check flags something that's actually fine, press Ignore and please open an issue.
Behind a reverse proxy or SSO
Library Doctor has its own login. If Authentik, Authelia or your proxy already protects it, you can switch the built-in login off with LD_AUTH=off. Only do that when something else is in front: Library Doctor can move files.
Behind a reverse proxy, also set:
LD_TRUSTED_PROXIESto your proxy's address or range (e.g.172.16.0.0/12for a proxy in Docker,127.0.0.1for one on the same host). Only then areX-Forwarded-For/X-Forwarded-Protobelieved, so the login lock-out sees each visitor's real address. WithLD_AUTH=off, Library Doctor then answers only those addresses; without it, only local network addresses.LD_ALLOWED_HOSTSto the name you open it by (e.g.ld.example.com). Requests for any other name are refused, which stops a web page from making your browser talk to Library Doctor (DNS rebinding). Strongly recommended withLD_AUTH=off. IP addresses andlocalhostalways work.
Refused requests show a red warning on the main screen for a week.
Settings (environment variables)
| Variable | Default | What it does |
|---|---|---|
TZ |
UTC | Time zone for the nightly scan |
LD_SCAN_HOUR |
3 |
Hour of the automatic scan until you set a time and days in Settings → Automatic scan (an out-of-range value like 99 turns it off) |
LD_TRASH_DAYS |
7 |
Days before the trash empties itself, until you pick 3, 7, 14 or 30 in Settings → Trash |
LD_KEEP_DAYS |
182 |
How long "Keep" hides an unwatched item |
LD_AUTH |
on |
off = no built-in login (only behind another login) |
LD_TRUSTED_PROXIES |
(empty) | Your reverse proxy's address(es)/ranges, comma-separated. See Behind a reverse proxy |
LD_ALLOWED_HOSTS |
(empty) | The name(s) you open Library Doctor by, comma-separated; other names are refused |
LD_PORT |
8790 |
Port inside the container |
LD_CLAMD_HOST / LD_CLAMD_PORT |
127.0.0.1 / 3310 |
Your ClamAV (clamd), for the Virus Scan check |
LD_CLAM_ROOT |
/scandir |
Where ClamAV sees the same media folder |
LD_SNOOZE_DAYS |
30 |
After "Search for better copies" finds nothing, hide the card this long, then search again |
LD_DOWNLOAD_WINDOW_END |
(unset) | If downloads only run at night, the hour the window ends (e.g. 7); a torrent is "stuck" after a whole window at 0%. Unset = after 24 hours |
LD_QUEUE_NOTIFY_HOUR |
8 |
Hour the Downloads check sends new problems to your notifications (the window end, if set) |
LD_PROTECT_TAGS |
(empty) | qBittorrent tags never offered for removal, comma-separated (private torrents never are) |
LD_INCOMPLETE_DAYS |
3 |
Days an item in the incomplete folder must be untouched (and unknown to every download client) before it's offered for the trash |
LD_INCOMPLETE_DIRS |
(empty) | Extra incomplete folders to check, comma-separated, as Library Doctor sees them (the download clients' own folders are found by themselves) |
Everything else (apps, API keys, folder mapping) is set on the Settings page and saved in /config/config.json. API keys stay on your server and are never shown again after saving.
Updating
docker compose pull && docker compose up -d
Thank you
Library Doctor talks to Plex, Radarr, Sonarr, Bazarr, Tautulli, Tdarr, Sportarr, Agregarr, ClamAV, Gotify, Discord, Telegram and ntfy, and uses ffmpeg and yt-dlp. It isn't connected to any of those projects.
Made by My Media Build. MIT licence.
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/spikey1965/library-doctor:latestRuntime arguments
- Web UI
http://[IP]:[PORT:8790]/- Network
bridge- Shell
sh- Privileged
- false
- Extra Params
--read-only --tmpfs /tmp --security-opt no-new-privileges:true
Template configuration
Port for the web page.
- Target
- 8790
- Default
- 8790
- Value
- 8790
The share with your films and shows (one folder that contains them all). Read-write: clean-ups move files into a hidden .library-doctor-trash folder inside it, which is instant on the same disk.
- Target
- /media
- Default
- /mnt/user/data/media
- Value
- /mnt/user/data/media
Settings, password and the database.
- Target
- /config
- Default
- /mnt/user/appdata/library-doctor
- Value
- /mnt/user/appdata/library-doctor
User that owns your media (Unraid default: 99 = nobody).
- Default
- 99
- Value
- 99
Group that owns your media (Unraid default: 100 = users).
- Default
- 100
- Value
- 100
Your time zone, for the nightly scan.
- Target
- TZ
- Default
- Europe/London
- Value
- Europe/London
Hour of the automatic scan until you set days and a time in Settings. On arrays whose disks spin down, scanning once a week (Settings) lets them sleep.
- Target
- LD_SCAN_HOUR
- Default
- 3
- Value
- 3
on = Library Doctor asks for its own password. Only set off if another login (Authelia, Authentik, your proxy) protects the page.
- Target
- LD_AUTH
- Default
- on
- Value
- on
Optional, behind a reverse proxy: its address or range (e.g. 172.17.0.0/16 for a proxy container on Unraid's default network). Only then are its forwarded visitor addresses believed. With the login off, only these addresses get an answer.
- Target
- LD_TRUSTED_PROXIES
Optional: the name(s) you open Library Doctor by, comma-separated (e.g. ld.example.com). Other names are refused, which stops DNS rebinding. Strongly recommended when the built-in login is off. IP addresses always work.
- Target
- LD_ALLOWED_HOSTS
Downloads: how many days an item in your download clients' incomplete folder must be untouched (and unknown to every client) before it's offered for the trash.
- Target
- LD_INCOMPLETE_DAYS
- Default
- 3
- Value
- 3
Optional: your ClamAV container's address, for the Virus Scan check.
- Target
- LD_CLAMD_HOST
Optional: if downloads only run at night, the hour that window ends (e.g. 7).
- Target
- LD_DOWNLOAD_WINDOW_END