Find Emby duplicate movies, unmatched titles and broken files without deleting anything

If you have run an Emby server for a few years, you know the feeling: the same movie appears twice, a poster is missing, a file that played fine last month now stops halfway, and the disk is full of things nobody watches. Emby itself has no report for any of this. Library Doctor is a plugin that finds these problems, shows what each one costs in disk space, and lets you clear them out without ever deleting a file. This tutorial walks through the whole routine, from duplicate movies to a reversible quarantine, for people who run their own servers.

Prerequisites

• Emby Server 4.10.1 or newer, on Linux, Windows or Docker.
• For the file check: nothing to install. The plugin uses the ffprobe and ffmpeg that come with Emby.
• For the quarantine: the Emby user needs write access to the library folders. On Linux that usually means the emby user; in Docker the media volumes must not be mounted read-only (no :ro). Without write access every report still works; only the quarantine cannot move files.
• A license key, an active subscription, a lifetime license within its update window, or the free 30-day trial. Without a valid license the plugin is stopped: no report, no file check, no moves.

Step 1 — Install and activate

1. Sign in to your MediaLab Works account, open Licenses and download the plugin DLL.
2. Copy the DLL into the Emby plugins folder and restart Emby Server:
   • Linux (package): /var/lib/emby/plugins/
   • Docker: the plugins folder inside your Emby config volume
   • Windows: %AppData%\Emby-Server\programdata\plugins\
3. Open Library Doctor in the Emby dashboard menu and click License. Paste your key and activate it, or enter your e-mail to start the trial. The plugin contacts the license server, binds the key to this server and shows the license as Active.

The license is checked once a day and at every Emby start. Without internet the plugin keeps working for 7 days after the last successful check. The same page can install an update or roll back to the previous version; restart Emby after either.

Step 2 — Read the header numbers

Open Library Doctor in the dashboard (administrators only). There is nothing to configure: the page reads your movie and episode libraries each time it opens. At the top you get video files, duplicate groups, the space to reclaim from duplicates, unmatched movies and the total size. Use it as a quick health score before you dig in.

Step 3 — Duplicates: know what Emby already groups

Before you start moving files, one important distinction. Emby groups files of one movie as versions only when they sit in the same folder with matching names; those show up as a version choice at playback and are not reported as duplicates by the plugin. Two files of the same movie in different folders become two separate items, and that is what Library Doctor finds.

• Movies are matched by their TMDb or IMDb id.
• Episodes are matched by series, season and episode number.
• Movies with neither id are matched by title (ignoring case, accents and punctuation) and year. Those groups are marked by title and year (no metadata id) — check, because two different movies can share a title and a year. Open both before you act.

Each group shows the versions side by side — resolution, HDR, codec, bitrate and size — with the best one first and marked best (higher resolution first, then HDR, then a more efficient codec such as AV1, HEVC or VP9, then bitrate), plus the space you would reclaim by keeping only that one. If you are on Emby 4.10 and same-TMDb copies were grouped automatically, they can still show as duplicates until you merge them; that is a known limitation, not a bug in the report.

Step 4 — Unmatched movies

The Unmatched movies section lists movies with no metadata id at all. That usually means a wrong title or year, a missing poster, and a movie that never appears in collections or recommendations. Click Open, then use Identify in Emby to pick the right movie. It disappears from the list the next time you open the page.

Step 5 — Check missing, broken and truncated files

Click Check the files. The check runs in the background, file by file, with a progress indicator; on a large library it takes a while and you can leave the page. For each movie and episode the plugin checks that the file exists, reads it with Emby's ffprobe (at most 30 seconds), then decodes the last 3 seconds of the video with Emby's ffmpeg (at most 60 seconds). Each problem is listed with its cause:

• missing from disk
• cannot be read, with the error
• no video track: the only "video" is an image, as in a file of random bytes
• no duration (broken header)
• zero duration
• the end is missing (incomplete download or copy): the last seconds cannot be decoded

Two honest limits: a file cut off very close to its end (for example at about 98%) may still pass because its last seconds contain decodable frames, and damage in the middle of a file is not looked for. A truncated .ts cannot be detected because it stores no duration. Results are kept in memory until Emby restarts. The check runs on demand only; there are no scheduled scans.

Step 6 — The space report

The Space section shows the total, then the space by library, by resolution (4K, 1080p, 720p, SD) and by video codec, plus the 20 largest files that no user has watched. It is the most useful page before a disk upgrade: it tells you whether your problem is a few huge 4K remuxes or a long tail of 720p files nobody opens.

Step 7 — Quarantine instead of deleting

When you click Quarantine on a weaker version (and confirm), the plugin moves the video file and the files next to it that share its name — subtitles, .nfo, images such as Movie.srt, Movie.en.srt, Movie.nfo and Movie-poster.jpg — into a folder named .medialab-de-sters at the root of the library folder that holds them, keeping their sub-folders. Because the folder is inside the same library folder, it is normally on the same disk and the move is instant. Emby then rescans the library.

The move is recorded before any file is touched. If a file cannot be moved (for example because of permissions), the files already moved are put back and no copy is left behind; if putting them back is not possible either, the entry stays in the Quarantine list so you can restore it. The list shows every moved title with its original location and size. Restore moves the files back exactly where they were and rescans; it refuses, without touching anything, if a file is both in quarantine and back at its original path. Files outside the library folders, and files already in .medialab-de-sters, are refused.

The plugin never overwrites or deletes a file. When you are sure, you delete the .medialab-de-sters folder from disk yourself; the space is freed only then. The list is stored in the plugin's data folder, so it survives an Emby restart — do not rename or move the quarantine folder while something in it may still need restoring.

Tips and troubleshooting

• Quarantine says "It could not be done": the message after it gives the reason. Usually Emby has no write access to the library folder. Check ownership and permissions on Linux, and make sure Docker volumes are not mounted with :ro.
• Restore says "It could not be done": a file is already at the original path, for example because you added the movie again. The restore refuses rather than overwrite.
• A quarantined file shows up in Emby with its new path: Emby has scanned the quarantine folder. The plugin will not quarantine such a file again; restore it, or delete the folder once you are sure.
• No online lookups: duplicates and unmatched titles are computed from the ids your server already stores. The only external contact is the licensing client. After a quarantine move or restore, the plugin starts the regular library scan, which may contact the metadata providers configured on your server.
• Emby Web only for the admin page. The work happens on the server, so apps and TVs only see the effect.

Conclusion

Library hygiene is not a one-off cleanup; it is a routine. Open the page, glance at the numbers, work through duplicates and unmatched titles, run the file check after big imports, and use the space report before you buy another disk. Because the quarantine only moves files inside the library folder and brings them back with one click, you can be decisive without being afraid. The full walkthrough is in the user guide, the version history is in the changelog, and the product page is at Library Doctor. If something behaves oddly, the knowledge base and FAQ are the next stop, and you can always contact us.