The Plex NFO Agent lets you use locally stored NFO metadata files to populate your movie and TV show libraries, rather than relying on online metadata sources. This is particularly useful for personal media collections, content not found in online databases, or when you simply prefer full control over your metadata.

The Plex NFO Agent is compliant with the widely used Kodi/XBMC NFO format. Most NFO generation tools output to this format. If you use a tool like TinyMediaManager, you can also configure it to use the Plex preset.

Notes: Music NFO support is not currently available. Libraries using this agent will not work with Syncing Watch State and Ratings.

Setting Up a Library with the NFO Agent

To use NFO metadata, you need to create a new library (or edit an existing one) and select the appropriate NFO agent.

Requires Plex Media Server version 1.43.1 or newer.

1. In Plex Web, navigate to Settings > Manage > Libraries.
2. Click Add Library (or edit an existing library).
3. Choose Movies or TV Shows as the library type and point it to your content folder.
4. Before saving, go to the Advanced pane.
5. From the Agent dropdown, select Plex NFO Movie (for movie libraries) or Plex NFO Series (for TV show libraries).
6. Click Add Library to save.

Tip: If you don’t see the NFO agent options in the dropdown, try refreshing the page in your browser.

Known Limitations

• Multi-part files: Movies split across multiple files (pt1, pt2) are not currently supported by the NFO Agent.
• Music: NFO support for music libraries is not currently available.
• Extras: NFO metadata for local extras (trailers, behind-the-scenes, etc.) is not supported. Use the standard Local Files for Movie Trailers and Extras or Local Files for TV Show Trailers and Extras naming conventions for extras.

File Structure and Naming

Movies

Each movie should be in its own folder. The NFO file can either be named movie.nfo (the generally accepted convention when each movie has its own folder) or match the exact filename of the movie file.

/Movies
  /A Movie (2026)
    A Movie (2026).mkv
    movie.nfo
    poster.jpg
    background.jpg
    logo.png
    square.jpg

Both naming approaches are valid:

movie.nfo

or

A Movie (2026).nfo

Related: For details on local image asset naming, see Local Media Assets – Movies

TV Shows

TV show libraries use up to three types of NFO files: one for the show itself, one optional file per season, and one per episode.

• tvshow.nfo – Placed in the root of the show folder. Highly recommended. Contains series-level metadata such as title, plot, genres, and cast.
• season.nfo – Placed inside each season folder. Mostly ignored and not required.
• Episode NFO files – Placed alongside each episode video file, with matching filenames. These are the minimum requirement.

/TV Shows
  /A TV Show (2026)
    tvshow.nfo
    poster.jpg
    background.jpg
    logo.png
    square.jpg
    /Season 01
      A TV Show (2026) - S01E01.mkv
      A TV Show (2026) - S01E01.nfo
      A TV Show (2026) - S01E01.jpg

Related: For details on local image asset naming, see Local Media Assets – TV Shows

NFO File Format

NFO files are XML documents saved with UTF-8 encoding and the .nfo file extension. The Plex NFO Agent follows the Kodi NFO specification. Below are the supported tags for each type.

Movie NFO (<movie>)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<movie>
  <title>A Movie</title>
  <originaltitle>A Movie</originaltitle>
  <plot>A description of the movie plot.</plot>
  <tagline>A short tagline for the movie.</tagline>
  <ratings>
    <rating name="imdb" max="10" default="true">
      <value>7.7</value>
      <votes>121637</votes>
    </rating>
    <rating name="themoviedb" max="10">
      <value>7.5</value>
      <votes>1550</votes>
    </rating>
  </ratings>
  <mpaa>PG-13</mpaa>
  <premiered>2026-03-15</premiered>
  <studio>Example Studios</studio>
  <genre>Action</genre>
  <genre>Adventure</genre>
  <tag>Marvel</tag>
  <country>United States</country>
  <set>
    <name>A Movie Collection</name>
    <overview>All movies in the series.</overview>
  </set>
  <uniqueid type="tmdb" default="true">123456</uniqueid>
  <uniqueid type="imdb">tt1234567</uniqueid>
  <credits>Writer Name</credits>
  <director>Director Name</director>
  <actor>
    <name>Actor Name</name>
    <role>Character Name</role>
    <order>0</order>
    <thumb>https://image.tmdb.org/t/p/w500/example.jpg</thumb>
  </actor>
  <thumb aspect="poster">https://example.com/poster.jpg</thumb>
  <fanart>
    <thumb>https://example.com/background.jpg</thumb>
  </fanart>
</movie>

TV Show NFO (<tvshow>)

This file must be named tvshow.nfo and placed in the root of the show folder.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<tvshow>
  <title>A TV Show</title>
  <plot>A description of the TV show.</plot>
  <mpaa>TV-14</mpaa>
  <premiered>2026-01-10</premiered>
  <status>Continuing</status>
  <studio>Example Network</studio>
  <genre>Drama</genre>
  <genre>Thriller</genre>
  <uniqueid type="tmdb" default="true">78901</uniqueid>
  <uniqueid type="imdb">tt7890123</uniqueid>
  <namedseason number="1">The Beginning</namedseason>
  <actor>
    <name>Actor Name</name>
    <role>Character Name</role>
    <order>0</order>
    <thumb>https://image.tmdb.org/t/p/w500/example.jpg</thumb>
  </actor>
</tvshow>

Episode NFO (<episodedetails>)

Episode NFO files are named to match the video file, with a .nfo extension instead of the video extension.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<episodedetails>
  <title>Pilot</title>
  <season>1</season>
  <episode>1</episode>
  <plot>The first episode of the show.</plot>
  <aired>2026-01-10</aired>
  <director>Director Name</director>
  <credits>Writer Name</credits>
  <actor>
    <name>Guest Star Name</name>
    <role>Guest Character</role>
    <thumb>https://image.tmdb.org/t/p/w500/example.jpg</thumb>
  </actor>
</episodedetails>

Unique IDs and Watch State

The Plex NFO Agent builds a stable internal identifier (GUID) from the IDs present in your NFO files. This means that as long as your NFO files contain consistent IDs, your watch status and play history will be preserved across rescans.

The agent uses IDs in the following priority order:

1. <uniqueid> with a type attribute (recommended). For example, <uniqueid type="tmdb" default="true">383498</uniqueid> will produce a stable GUID like tv.plex.agents.nfo.movie://movie/tmdb_383498.
2. <id> as a fallback. If only a generic <id> field is present (e.g. <id>858024</id>), the GUID will be based on that value.

For the best results, ensure your NFO generation tool writes <uniqueid> tags with appropriate type attributes (such as tmdb, imdb, or tvdb).

Cast, Crew, and Images

The NFO Agent reads cast and crew information from the <actor>, <director>, and <credits> (writer) tags.

• Actor images: If your NFO file includes a <thumb> element inside each <actor> block pointing to an image URL, the agent will use it as the actor’s profile photo. If no thumb is provided, no profile picture will be shown.
• Discover credits: The “Discover” cast credits feature (allowing you to browse an actor’s filmography) is only available when using a Plex online provider. If you want Discover credits, place a Plex provider (e.g. “Plex Movie”) ahead of or alongside the NFO provider in a Custom Metadata Agent configuration, and ensure your NFO files do not include cast data — the Plex provider will supply cast information with Discover links instead.

Online Image Fallback

While the NFO Agent does not require any online connectivity, it will attempt to fetch remote images if:

• Your NFO file references online image URLs (e.g. in <thumb> or <fanart> tags).
• No local image assets are provided alongside the media file.

If you provide local image assets (such as poster.jpg, background.jpg, etc.), those will always be preferred.

Custom Metadata Agent Configuration

You can combine the NFO Agent with other metadata providers by creating a Custom Metadata Agent. This is useful if you want NFO files as your primary metadata source but still want supplementary data (like extras or online artwork) from Plex’s built-in providers.

1. Navigate to Settings > Agents.
2. Create a new Custom Metadata Agent.
3. Add the appropriate NFO provider (e.g. “Plex NFO Movie”) as the primary provider.
4. Optionally add additional providers such as “Plex Movie” or “Plex Local Media” below it.

Note: If you want embedded metadata from MP4 files to take priority over NFO metadata, add the “Plex Local Media” provider above the NFO provider in the list.

Supported Metadata Tags Reference

The following tables summarize which Kodi NFO tags are read by the Plex NFO Agent.

Movie Tags

Tag	Description
<title>	Movie title
<originaltitle>	Original title (if different from localized title)
<plot>	Synopsis / description
<tagline>	Short tagline
<ratings>	Rating block containing one or more <rating> entries with name, max, <value>, and <votes>
<mpaa>	Content rating (e.g. PG-13, R)
<premiered>	Release date in YYYY-MM-DD format
<studio>	Production studio
<genre>	Genre (multiple tags supported)
<tag>	Collection tag (multiple tags supported)
<country>	Country of origin
<set>	Movie collection, containing <name> and <overview>
<uniqueid>	External ID with type attribute (e.g. tmdb, imdb)
<id>	Fallback identifier
<credits>	Writer name
<director>	Director name
<actor>	Cast member, containing <name>, <role>, <order>, <thumb>
<thumb>	Poster or other artwork URL
<fanart>	Background artwork URL(s)

TV Show Tags (tvshow.nfo)

Tag	Description
<title>	Series title
<plot>	Series synopsis
<mpaa>	Content rating
<premiered>	Series premiere date in YYYY-MM-DD format
<status>	Series status (e.g. Continuing, Ended)
<studio>	Network or studio
<genre>	Genre (multiple tags supported)
<uniqueid>	External ID with type attribute
<namedseason>	Custom season name with number attribute
<actor>	Cast member, containing <name>, <role>, <order>, <thumb>

Episode Tags (per-episode .nfo)

Tag	Description
<title>	Episode title
<season>	Season number
<episode>	Episode number
<plot>	Episode synopsis
<aired>	Air date in YYYY-MM-DD format
<director>	Director name
<credits>	Writer name
<actor>	Guest cast, containing <name>, <role>, <thumb>

NFO Generation Tools

You don’t need to write NFO files by hand. Several popular tools can generate Kodi-compatible NFO files for your media library:

• TinyMediaManager – A full-featured media management tool with a Plex preset for NFO output. Recommended for most users.
• FileBot – A file renaming and organizing tool that can generate NFO files using its nfo.groovy script. Note that FileBot-generated NFO files may be more sparse than those from TinyMediaManager (for example, they may omit <premiered>, actor images, or <uniqueid> tags).
• Manual creation – NFO files are plain XML text files that can be created with any text editor. Use the templates above as a starting point.

Ratings

The Plex NFO Agent supports external ratings from sources like TMDB, IMDb, and TVDB. Ratings can be included in your NFO files using the <ratings> block:

<ratings>
  <rating name="imdb" max="10" default="true">
    <value>7.7</value>
    <votes>121637</votes>
  </rating>
  <rating name="themoviedb" max="10">
    <value>7.5</value>
    <votes>1550</votes>
  </rating>
</ratings>

The name attribute identifies the rating source (e.g. imdb, themoviedb, thetvdb). Set default="true" on whichever rating you want displayed as the primary rating in Plex.

Multi-Episode Files

When a single video file spans multiple episodes (e.g. S01E01-E02), the NFO Agent supports this by using multiple <episodedetails> blocks within a single NFO file. Name the NFO file to match the video file:

A TV Show (2026) - S01E01-E02.mkv
A TV Show (2026) - S01E01-E02.nfo

Inside the NFO file, include a separate <episodedetails> block for each episode:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<episodedetails>
  <title>Part One</title>
  <season>1</season>
  <episode>1</episode>
  <plot>The first part of the story.</plot>
  <aired>2026-01-10</aired>
</episodedetails>
<episodedetails>
  <title>Part Two</title>
  <season>1</season>
  <episode>2</episode>
  <plot>The conclusion of the story.</plot>
  <aired>2026-01-10</aired>
</episodedetails>