Emby file naming: how to get your library matching correctly

Emby shares most of its naming conventions with Jellyfin, which forked from it, and overlaps heavily with Plex. If you already have a library that Plex reads correctly, Emby will read most of it. The differences are in a handful of specific places, and those are what this page is about.

Folder structure first

Emby matches at the folder level for movies and at the folder plus filename level for TV. Give it the structure it expects and most problems never happen:

Movies/
  Dune Part Two (2024)/
    Dune Part Two (2024).mkv

TV/
  The Last of Us (2023)/
    Season 01/
      The Last of Us (2023) - S01E03 - Long Long Time.mkv

The year in brackets on the folder is not optional in practice. It is how Emby tells apart two things with the same name, and it turns a fuzzy search into a precise one.

One folder per movie matters more in Emby than in Plex, because that folder is the unit Emby uses for extras, subtitles, artwork and multiple versions. A flat Movies folder with a hundred loose .mkv files will mostly work and will lock you out of half the features.

Pinning to a provider ID

When Emby keeps matching the wrong thing, stop fighting the title and pin it:

Dune Part Two (2024) [tmdbid-693134]/
The Last of Us (2023) [tvdbid-392256]/

Emby reads tmdbid, tvdbid and imdbid in square brackets on the folder name. This is the single most useful trick in the whole system and almost nobody uses it. It is also the correct answer for anything with a generic name, a remake, or a foreign title that the scraper keeps resolving to the wrong entry.

Multiple versions of the same movie

This is where Emby is genuinely nicer than the alternatives. Put the versions in the one movie folder and mark each with a dash and a label:

Dune Part Two (2024)/
  Dune Part Two (2024) - 2160p.mkv
  Dune Part Two (2024) - 1080p.mkv
  Dune Part Two (2024) - Directors Cut.mkv

Emby collapses those into one entry with a version picker rather than three separate movies. The rule is the base name, then space hyphen space, then whatever you want the version called. Get the separator wrong and you get three entries.

TV: specials and the numbering that trips people

Specials go in Season 00, numbered as episodes of season zero:

The Last of Us (2023)/
  Season 00/
    The Last of Us (2023) - S00E01 - Making Of.mkv

Episodes spanning two files use a range, and Emby handles both common spellings:

Show Name - S01E01-E02.mkv

Multi-part single episodes, meaning one episode split across two files rather than a double episode, use part suffixes instead:

Show Name - S01E05 - part1.mkv
Show Name - S01E05 - part2.mkv

The distinction matters because the first one is two episodes in the database and the second is one episode with two files. Getting it backwards produces a library where watched state behaves strangely and nobody can work out why.

Anime

Everything on the general naming page about absolute versus aired ordering applies to Emby unchanged. The short version: your files are probably numbered absolutely, TVDB thinks in aired seasons, and there is no arithmetic that converts one to the other.

Emby's practical path is to rename to explicit SxxExx in your chosen provider's aired order and use a single metadata provider for that series. Mixing TVDB artwork with AniDB episode data is how you end up with correct-looking images over wrong titles.

Extras

Emby recognises extras by subfolder name inside the movie or show folder:

Dune Part Two (2024)/
  Dune Part Two (2024).mkv
  behind the scenes/
  deleted scenes/
  interviews/
  trailers/
  featurettes/

The names are fixed and lowercase is fine. Files inside are named freely, because the folder is what assigns the type. A trailer can also sit beside the movie as Dune Part Two (2024)-trailer.mkv, with the hyphen suffix and no space.

NFO sidecars, and when to reach for them

For anything with no online match, home video, a recorded talk, an old match, stop trying to make the scraper cooperate. Two clean answers:

Use a library type that does not scrape. Emby's Home Videos and Photos library type does not go looking for matches. Low effort, usually correct.
Write an NFO. A plain XML file beside the video, same base name, .nfo extension. Then set the library to prefer local metadata and untick the internet providers, and Emby uses your data.

Emby also writes NFOs itself if you turn on the NFO metadata saver, which is worth doing purely as a backup: your corrections then live next to the files rather than only in the server database, and they survive a rebuild.

Emby does not read titles out of the video container. Setting a title inside an MKV with MKVToolNix does nothing. Library metadata comes from the filename, the online providers, and NFO sidecars. That is the entire list.

The settings that decide whether any of this works

Library type. A Movies library will not parse SxxExx and a TV library will not treat a loose file as a movie. Half of all "Emby is not matching" is a library pointed at the wrong content type.
Metadata downloaders. Per library, per type. If you have unticked everything to stop bad matches, nothing will match at all.
Local metadata and images. Controls whether NFO and sidecar artwork are read. Off means your .nfo is ignored no matter how correct it is.
Preferred metadata language and country. Drives which title comes back, which is why a correctly named foreign film can show up under a title you do not recognise.

After a rename or a settings change, run a scan with "Refresh metadata" and "Replace existing metadata" rather than a plain scan. A plain scan looks for new files, and a renamed file often is not treated as new.

Renaming an existing Emby library

Two things to protect.

Watch state lives in the database, not in the file

Emby tracks items by its internal ID. Rename files underneath it and, on the next scan, Emby usually sees the old path as gone and the new path as new, which means a new item with no watch history. Scan after renaming, check a few items, and if history has been lost the safe recovery is restoring the database rather than renaming things back.

Take the subtitles with you

Sidecar subtitles are attached by base name and nothing else, so renaming the video orphans them. Rename them in the same pass, or use a tool that carries them. That whole topic, including language codes and the forced and SDH flags, is on the subtitle page.

Checklist

One folder per movie, year in brackets on the folder
[tmdbid-…] or [tvdbid-…] on anything that keeps mismatching
Versions in one folder, separated by space hyphen space
TV as Season 01 with the leading zero, specials in Season 00
Extras in the fixed subfolder names
Library type, downloaders and local metadata all set before blaming the filenames
Full refresh scan after renaming, and check watch state on a few items