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

Every self-hosted library drifts. A movie gets added twice because two files landed in different folders, a few titles never matched and sit there without a poster, a copy was interrupted halfway and nobody noticed, and the disk keeps filling up. Jellyfin has no single report for any of this, so you usually find out by accident. Library Doctor is a Jellyfin plugin that collects those problems in one admin page, shows what each one costs in disk space, and lets you fix them without ever deleting a file.

This tutorial walks through the whole flow: finding jellyfin duplicate movies, dealing with unmatched titles, checking file integrity, reading the space report, and using the quarantine as a safety net.

Prerequisites

• Jellyfin Server 12.2 or newer (Linux, Windows or Docker).
• A MediaLab Works account with a license that covers the plugin (active subscription, lifetime license within its update window, the Jellyfin bundle, or the free 30-day trial).
• ffprobe and ffmpeg for the integrity check — they come with jellyfin-ffmpeg, and the plugin uses the same paths Jellyfin uses for transcoding.
• Write access to the library folders for the Jellyfin user, if you want to use the quarantine. On Linux that is usually the jellyfin 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.

The plugin is open source (GPL-3.0), and the source code of each version is in your account.

Step 1 — Install and activate

The recommended route is your private plugin repository:

1. In your MediaLab Works account open Licenses → Jellyfin plugin repository and click Create address. Copy it — it contains a token, so keep it private.
2. In Jellyfin open Dashboard → Plugins → Repositories, click +, name it (for example MediaLab Works), paste the address and save.
3. In Dashboard → Plugins → Catalog find Library Doctor by MediaLab, click Install, then restart Jellyfin.

There is also a public catalog at https://medialab.works/jellyfin/manifest.json, and a manual zip install if you prefer. After restarting, open the plugin page under Dashboard → Plugins → Library Doctor by MediaLab, go to License, paste your key and click Activate with key. No key yet? Start the 30-day trial from the same page.

Step 2 — Open the dashboard page

Library Doctor appears in the Jellyfin dashboard menu and is visible to administrators only. There is nothing to configure: the page reads your movie and episode libraries each time it opens.

At the top you get the numbers: video files, duplicate groups, the space to reclaim from duplicates, unmatched movies and the total size. Treat this as your library health snapshot before you touch anything.

Step 3 — Review duplicate movies and episodes

This is the part most people come for. Jellyfin already groups multiple files of the same movie as versions when it recognizes them, but when the same movie sits in two different folders it usually becomes two separate items. Library Doctor finds those groups.

• Movies are matched by their TMDb or IMDb id.
• Episodes are matched by series, season and episode number.
• Movies with no metadata id are matched by title and year, ignoring case, accents and punctuation. 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 acting.

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). You also see the space you would reclaim by keeping only that one.

You have two actions, and neither one deletes anything:

• Group as versions keeps every file and shows them as versions of one title, using Jellyfin's own version grouping. No file is moved.
• Quarantine moves a weaker version out of the way (see Step 6).

Step 4 — Fix unmatched movies

The Unmatched movies section lists movies with no metadata id at all. These are usually the ones with a wrong title, year or poster, and they tend to be missing from collections and recommendations.

Click Open on an entry, then use Jellyfin's Identify on the movie to pick the right match. It disappears from the list the next time you open the Library Doctor page.

Step 5 — Run the integrity check and read the space report

Click Check the files. The check runs in the background, file by file, and shows its progress; on a large library it takes a while and you can leave the page. It is on demand only — there are no scheduled scans.

For every movie and episode file it reports files that are:

• missing from disk;
• cannot be read, with the error;
• have no real video track (for example a file of random bytes in which ffprobe guesses a picture);
• have no duration (a broken header) or zero duration;
• are truncated: the last 3 seconds are decoded, and a file whose end cannot be decoded is flagged as an incomplete download or copy.

Be aware of the limits: a file cut off very close to its end can still have decodable frames in its last seconds and pass, damage in the middle of a file is not looked for, and a truncated .ts cannot be detected because there is no stored duration.

Below that, the space report gives you 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. That last list is often the most useful one when you need room for something new.

Step 6 — Quarantine instead of deleting

When you click Quarantine on a 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, 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, so the move is instant. Jellyfin then rescans the library.

The move is recorded before any file is touched. If a file cannot be moved (permissions, for example), the files already moved are put back and nothing is left behind; if putting them back is not possible either, the entry stays in the quarantine list so you can restore it. Files outside the library folders, and files already in a .medialab-de-sters folder, are refused.

The Quarantine 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. The plugin never overwrites or deletes a file — once you are sure, you delete the .medialab-de-sters folder from disk yourself.

Tips and troubleshooting

• The quarantine does nothing. Check that the Jellyfin user can write to the library folders and that Docker volumes are not mounted :ro. All reports work without write access; only the move fails.
• A duplicate group looks wrong. If it is marked by title and year, verify both entries before grouping or quarantining — remakes can share a title, and sometimes a year.
• The check takes long. That is normal on a big library; it runs in the background and you can leave the page. Results are kept in memory only, so they are not persisted between restarts.
• Privacy. There is no external contact besides the licensing client, and no online metadata lookups: duplicates and unmatched titles are computed from the ids your server already stores. The file check runs the server's ffprobe locally. After a quarantine move or restore, the plugin starts the regular library scan, which may contact the metadata providers configured on your server — that is server behavior, not the plugin's.

Conclusion

Library hygiene is mostly about seeing the problems before they grow. Library Doctor gives you one page for duplicate movies and episodes, unmatched titles, missing or broken files, and where the space actually goes — and it fixes things by grouping or moving files into a quarantine you can restore, never by deleting. Install it from your plugin repository, run the check once, and keep the page in your monthly maintenance routine. The Library Doctor product page has the full feature list, the user guide covers installation and daily use in detail, and the changelog shows what changed in each version. Questions? The knowledge base, the FAQ and the contact page are the places to start.