Organizing a Jellyfin Library: Naming and Metadata

A Jellyfin server is only as good as the library behind it. Get the file naming right and Jellyfin matches almost everything on the first scan — correct posters, summaries, and episode order. Get it wrong and you’re scrolling through The.Movie.2021.2160p.WEB-DL.x265-GROUP tiles with no artwork and shows filed in the wrong order.

This post covers the naming convention Jellyfin expects, which metadata providers to turn on (and which ones are plugins, not built-ins), and how to repair an existing messy library. It’s the third post in the Jellyfin, Done Properly series, after installation and hardware transcoding.

The name is the search query

Jellyfin doesn’t read the contents of your files to identify them — it reads their names. The scanner takes the folder and file name, extracts a title and year (or a series, season, and episode), and hands that to its metadata providers as a lookup. A clean name is an unambiguous query; a release-group name is a bad one. This is the single idea the whole post rests on, so here it is as a picture:

The takeaway: a name Jellyfin can parse is a name Jellyfin can match.

The naming convention Jellyfin expects

Match this layout and matching becomes hands-off. It follows Jellyfin’s official conventions for naming movies and naming shows.

Movies/
Dune (2021)/
  Dune (2021).mkv
The Matrix (1999)/
  The Matrix (1999).mkv

Shows/
Firefly (2002)/
  Season 01/
    Firefly S01E01.mkv
    Firefly S01E02.mkv
  Season 00/
    Firefly S00E01.mkv

The rules that matter:

• One folder per movie, named Title (Year). The year disambiguates remakes — there are several films called “Dune” and “The Mummy”. The video file inside repeats the folder name.
• TV uses series → Season NN → Series SxxEyy. Jellyfin’s docs are explicit here: name the season folder Season 01, and do not abbreviate it to S01 or SE01. The SxxEyy pattern in the file is what maps it to an episode.
• Specials live in Season 00. Anything the provider lists as a special (episode number 0) belongs there, named SxxE00 style, so it doesn’t shove your real episode numbering out of order.

The Jellyfin trick Plex doesn’t have: provider IDs in the name

Jellyfin lets you embed a metadata provider ID directly in the folder or file name, in square brackets, to force an exact match instead of a text search:

Dune (2021) [tmdbid-438631]/
Dune (2021) [tmdbid-438631].mkv

tmdbid- points at The Movie Database, tvdbid- at TheTVDB, and imdbid- at IMDb (whose IDs look like [imdbid-tt1234567]). This is worth reaching for when a title is genuinely ambiguous or a provider keeps grabbing the wrong entry — the number is unambiguous where a title string isn’t. It’s optional; plain Title (Year) is enough for the vast majority of a library.

Turn on the right providers

Here is the part that trips up people coming from Plex, whose “agents” are all built in. In Jellyfin, only a few providers ship in the box; the rest are plugins you install from Dashboard → Plugins → Catalog.

Set the provider order per library in Dashboard → Libraries → (your library) → Manage Library → Metadata downloaders. The list is priority-ordered — the top provider that returns a result wins, and lower ones fill gaps. Jellyfin’s metadata documentation lists TMDb, the OMDb API, and local NFO as the built-in set, with everything else coming from the Plugin Catalog.

Task 1: Fix a movie or show that matched wrong

Even with good naming, a few items land on the wrong entry — a poster for the wrong film, or a foreign remake. Jellyfin’s Identify feature re-runs the lookup with your correction.

Task 2: Refresh metadata without wiping your fixes

Once you’ve corrected items, understand Jellyfin’s Refresh metadata dialog before you use it, because one option undoes manual work. Open it from an item or a whole library’s ⋯ → Refresh metadata:

• Scan for new and updated files — the gentlest: only looks for files that changed on disk. Safe to run anytime.
• Search for missing metadata — fills empty fields only; leaves everything you already have (including your fixes) intact.
• Replace all metadata — refetches everything from the providers and overwrites current values. This is what you want after an Identify correction, but on a whole library it will also revert unlocked manual edits.

Task 3: Tidy the display — sort names and library order

A library full of “The …” titles clusters everything under T. Fix it with a sort name: edit the item, set Sort Name to the title minus the leading article (“The Matrix” → “Matrix” so it files under M), and lock it. Do the same for series that should sort by a different word than their display title.

For the shelf order itself, each library’s Display settings (in Manage Library) control the default sort — by name, release date, date added, or community rating — and whether Jellyfin groups movies into collections. These are per-library, so your Movies shelf can sort by release year while Shows sorts alphabetically.

What’s next

A cleanly-named, correctly-matched library is the payoff of the Jellyfin series: installation, free hardware transcoding, and now tidy metadata. From here it’s just adding content — ideally through an automated pipeline that names everything correctly on the way in, so the library stays clean without you touching the Identify screen again.

Related posts:

• Install Jellyfin on a NAS or Proxmox LXC — where the library lives
• Free Hardware Transcoding in Jellyfin — smooth 4K playback for the library you just organized
• Organizing a Plex Library: Naming, Agents, and Metadata — the Plex equivalent, same file layout
• Plex vs Jellyfin: Which Media Server Should You Run? — if you’re still choosing between them
• What Is the Arr Stack? Sonarr, Radarr, and Prowlarr Explained — the pipeline that names files correctly on import
• Media Runtime-Mismatch Audit — the script that catches renamed-wrong files
• Tailscale Subnet Router — reach Jellyfin remotely and shield your download client’s IP