Plex Media Server versions 1.25.9 and newer provide a match-hinting feature that can help advanced users gain more control over how their TV series files are scanned and matched. This is done by creating simple text files named (exactly) “
Warning: This is an advanced feature and is not intended for general users.
Match hinting is controlled by text files with the exact name
.plexmatch located in either a series directory or a season directory. Each
.plexmatch file affects matching for the directory it’s in; a
.plexmatch file at the top level of a series also affects directories beneath it. For instance, imagine a setup with this directory structure:
/TV Shows /ShowName .plexmatch /Season 1 Show S01E01.mkv /Season 2 .plexmatch S02E01.mkv
.plexmatch file in the
ShowName directory would affect matching for both media files, while the one in
ShowName/Season 2 would affect only
Note: Many text editors (e.g. Notepad and TextEdit) will save files with a .txt extension by default. In such a case, you’ll need to manually rename the file to
.plexmatch exactly by removing the extension. (If you leave it as “plexmatch.txt” or “.plexmatch.txt”, it will not work.)
.plexmatch file is a line-delimited text file. Leading and trailing whitespace on each line is ignored. Lines that are blank, contain only whitespace, or start with a
# character (possibly after leading whitespace), are ignored.
Each line may introduce a hint directive. A hint directive is composed of a hint name, a colon, and a hint value; like so:
hint1: value1 hint2: value2 hint3: value3
Whitespace at the start and end of the hint name and hint value is ignored. Hint names are case-insensitive.
Series and season match hinting
Series and season match hinting allows you to tell Plex Media Server what series and season a directory contains with precision. Match hint information provided in a
.plexmatch file overrides the directory and filenames, allowing greater control over matching without requiring you to rename your existing files.
Several match hints are supported:
showare synonymous. Either one can be used to set the title of the series for matching purposes, overriding the series directory name.
seasonsets the season number. This would normally be used in a season directory (overriding any number provided by the directory name), particularly when using a separate top-level directory for each season in a series (rather than grouping them all under a series directory as usual).
yearsets the release year of the series.
imdbidset the numeric ID of the series from TheTVDB, The Movie Database, or IMDb. This overrides any
yearhints, as well as the series directory name.
imdbidhints can optionally include the
guidsets a Plex URI-style media identification GUID, in the format
For example, a file that sets the title, year, and season for a top-level directory called
CoolShowSecondSeason might look like this:
# This directory contains the second season of Cool Show Title: Cool Show # The series' first season originally aired in 2018 Year: 2018 Season: 2 # We could also add a tvdbid: hint if we knew the ID for # Cool Show, but we'd still need to provide the season # hint as well.
Episode match hinting
Episode match hinting allows you to tell Plex Media Server which particular episode a file contains, even if the scanner would normally be unable to parse its filename.
Episode match hints are named
ep for short (both names are supported). The hint value uses the format
simpleEpisodeNumber: filename. Whitespace before and after the filename is ignored, but the episode number must be followed immediately by the colon.
Supported episode number formats include:
SP[X], meaning Special (season 0) episode X. e.g.
[X], meaning episode X of the current directory’s season (defaulting to 1). e.g.
E02, or simply
S[X]E[Y], meaning episode Y of season X. e.g.
All formats also support a trailing hyphen-separated continuation string specifying that a file contains a range of episodes. Supported formats include:
[X], meaning a file contains multiple episodes of the current season. e.g.
S[X]E[Y], meaning a file contains multiple episodes of the specified season. e.g.
When the filename specified by an episode hint matches the name of a file in the directory, that file will be scanned in using the episode number specified in the hint, ignoring any number that would normally be parsed from the filename. If present, a season number specified in the hint will also override any season number in the filename, as well as in the directory name or in a
season hint. For instance:
# Regular episodes with tricky filenames Episode: 01: Pilot.mkv ep: 12: Episode 12 - Finale Part 2.mkv # Specials ep: SP01: Some Unnumbered Special.mkv ep: SP03: Some Special Subseries 1.mkv ep: SP04: Some Special Subseries 2.mkv
.plexmatch file for a series directory may specify episode hints for any file beneath it by using a relative path:
ep: SP02: Season 1/Bonus/Bonus Clip 1.mkv ep: SP04: Season 2/Bonus/Bonus Clip 1.mkv
Tip!: Forward-slashes (
/) will always work as path delimiters, even on Windows. Backslashes (\) only work on Windows, so you may want to avoid them.
.plexmatch files in directories below the main series can only specify episode hints for the directory they’re in.