Metadata · Agents · Library · 11 min read · October 8, 2026

Plex Metadata Agents and Scanners: Getting Correct Matches Every Time

How Plex Identifies Your Media

When you add files to Plex, two systems work together. The scanner reads your folder structure and file names to determine what each file might be. The agent then queries online databases (TMDB, TVDB, MusicBrainz) to fetch metadata: posters, descriptions, ratings, cast lists, and more.

When matching fails, it's almost always because the scanner couldn't parse your file/folder names correctly, not because the agent database is wrong.

Naming Your Files Correctly

Movies

The Plex Movie scanner expects:

Movies/
  Movie Name (Year)/
    Movie Name (Year).mkv

The year is critical for disambiguation. "The Thing (1982)" vs "The Thing (2011)" — without the year, Plex guesses wrong half the time.

TV Shows

TV Shows/
  Show Name/
    Season 01/
      Show Name - S01E01.mkv

The S01E01 format is non-negotiable. Plex supports variations (1x01, s01.e01) but S01E01 is the most reliable across all scanners.

Agent Priority and Configuration

Plex uses a priority list of agents. If the first agent can't find a match, it tries the next one. Configure agent priority in Settings → Agents.

For movies, the recommended order:

1. Plex Movie: The new default — combines TMDB and IMDB data
2. The Movie Database: Fallback with extensive international film coverage
3. Personal Media: For home videos and media without online metadata

For TV shows:

1. Plex TV Series: The new default — merges TVDB and TMDB
2. TheTVDB: Best for anime and niche shows with community-maintained data

Fixing Mismatches

When Plex matches your file to the wrong title:

1. Click the item → three dots → "Fix Match"
2. Search for the correct title manually
3. Select the right result from the list
4. Click "Save" — Plex re-fetches all metadata

For persistent mismatches, rename the file/folder to include the TMDB or TVDB ID: Movie Name (Year) {tmdb-12345}. This forces an exact match.

Custom Metadata

For personal media, home movies, or content not in any database:

• Use the "Personal Media" agent type
• Create a .nfo file alongside your media with XML-formatted metadata
• Place poster.jpg and fanart.jpg in the same folder for artwork
• Plex reads these local files instead of querying online databases

Refresh vs Scan

• Scan Library: Looks for new, changed, or removed files — fast, runs automatically
• Refresh Metadata: Re-fetches metadata from agents for existing items — useful after agent changes or to update ratings/descriptions
• Analyze: Re-examines file properties (codecs, bitrate, chapters) — useful after remuxing

Don't refresh metadata unless you have a reason. It's slow on large libraries and can overwrite manual edits.