Set Up an Anime Library in Plex That Actually Works
Anime is notoriously difficult to organize in Plex. Series have multiple seasons that aired years apart under different names, episodes get numbered differently between databases, OVAs and specials do not fit neatly into standard TV show structures, and metadata agents frequently match the wrong series entirely. This guide covers everything you need to get anime working properly in Plex — from folder structure and naming to metadata agents and artwork.
Why Anime Is Hard for Plex
Plex was designed around Western TV conventions: a show has numbered seasons, episodes within those seasons, and metadata sources (TMDb, TheTVDB) that organize content accordingly. Anime breaks these assumptions:
- Multiple naming conventions: "Shingeki no Kyojin" vs. "Attack on Titan" vs. "進撃の巨人" — the same show has different names in different databases.
- Absolute episode numbering: Many anime series use absolute episode numbers (Episode 1-366) rather than Season/Episode format. TheTVDB and TMDb may number them differently.
- Sequel series with different names: "My Hero Academia Season 7" might be listed as a separate series called "Boku no Hero Academia 7th Season" on some databases.
- OVAs, specials, and movies: These exist in a gray area — sometimes they are part of a season, sometimes separate entries, sometimes numbered as "Season 0" specials.
The result: Plex frequently grabs wrong metadata, shows episodes in the wrong order, or cannot find a match at all. Fixing this requires the right scanner, the right agent, and consistent naming.
Step 1: Choose Your Metadata Source
The metadata agent determines where Plex pulls episode titles, descriptions, artwork, and ordering from. For anime, you have several options:
TheTVDB (Default)
TheTVDB is Plex's default TV metadata source and works adequately for mainstream anime dubbed in English. Its strengths: English-language metadata, familiar Season/Episode numbering for many popular series. Its weaknesses: inconsistent handling of long-running series, frequent ordering disagreements with how episodes are numbered in Japan, and poor coverage of lesser-known series.
If your anime library is small and mainly popular dubbed series, TheTVDB is fine. For anything beyond that, you need a dedicated anime agent.
HAMA (HTTP AniDB Metadata Agent)
HAMA is the most popular community anime metadata agent for Plex. It pulls data from AniDB (the largest anime-specific database), with fallbacks to TheTVDB and TMDb for additional artwork. HAMA handles:
- Accurate Japanese and romaji titles alongside English titles
- Absolute episode numbering that matches how anime is actually released
- Proper grouping of related series, OVAs, and movies
- Anime-specific artwork including character art and Japanese promotional images
HAMA requires installation of both the agent and the ASS (Absolute Series Scanner) — the scanner tells Plex how to read your folder structure, and the agent fetches the metadata.
Kometa (formerly Plex Meta Manager)
Kometa is not a metadata agent itself — it is an automation tool that runs on a schedule and enhances your existing metadata. For anime, it can automatically create collections ("Studio Ghibli," "Shonen Jump"), add genre tags, apply custom overlays (resolution badges, audio format indicators), and enforce naming consistency. It works alongside HAMA or the default agent.
Step 2: Install the Absolute Series Scanner
The Absolute Series Scanner (ASS) replaces Plex's default scanner and understands anime-style file naming. Without it, even with the right agent, Plex may misidentify episodes.
- Download
Absolute Series Scanner.pyfrom its GitHub repository. - Place it in the Plex scanners directory:
- Windows:
%LOCALAPPDATA%\Plex Media Server\Scanners\Series\ - Linux:
/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Scanners/Series/
Create the Scanners/Series/ directories if they do not exist. After placing the file, restart Plex.
Step 3: Install HAMA
- Download the HAMA agent bundle from its GitHub repository.
- Place the entire
Hama.bundlefolder in the Plex plug-ins directory:
- Windows:
%LOCALAPPDATA%\Plex Media Server\Plug-ins\ - Linux:
/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-ins/
Restart Plex. When creating or editing a library, you should now see "HamaTV" as an available agent option.
Step 4: Folder Structure and Naming
Proper naming is the difference between Plex matching everything correctly and a library full of mismatched metadata. Use this structure:
Standard Series
Anime/Attack on Titan [tvdb-267440]/Season 01/Attack on Titan - S01E01 - To You, in 2000 Years.mkv
The [tvdb-267440] tag in the folder name forces a match to the correct TheTVDB entry. This prevents Plex from guessing wrong. You can find the TheTVDB ID by searching for the show on thetvdb.com and noting the number in the URL.
Absolute Numbering
If you prefer absolute episode numbering (Episode 1-366 instead of Season/Episode):
Anime/Naruto Shippuden [anidb-4880]/Naruto Shippuden - 001.mkv
When using HAMA with ASS, the scanner reads the absolute number and maps it to the correct AniDB episode. The [anidb-4880] tag locks the match.
OVAs, Specials, and Movies
Place specials in a Season 00 folder (TheTVDB convention) or in a Specials folder:
Anime/Attack on Titan [tvdb-267440]/Season 00/Attack on Titan - S00E01 - Ilse's Notebook.mkv
Movies related to a series can either go in the same library with a year tag, or in a separate movies library:
Anime Movies/Demon Slayer - Mugen Train (2020)/Demon Slayer - Mugen Train (2020).mkv
Step 5: Create the Library
- Go to Settings > Libraries > Add Library.
- Choose TV Shows (even though it is anime — Plex treats anime as TV).
- Add your anime folder.
- Under Advanced: set the Scanner to Absolute Series Scanner, and the Agent to HamaTV.
- Save and let it scan.
The first scan may take time, especially for large libraries, as HAMA fetches metadata from AniDB (which has rate limits). Do not worry if it seems slow — it caches data for subsequent scans.
Troubleshooting Common Anime Issues
Wrong Series Matched
If Plex matched the wrong series, click the show, go to ... > Fix Match, and search manually. Use the AniDB ID or TheTVDB ID to force the correct match. Adding the ID tag to the folder name (Step 4) prevents this for future scans.
Episodes in Wrong Order
This usually means the naming convention does not match what the agent expects. If using TheTVDB ordering with HAMA, make sure your files use S01E01 format. If using AniDB absolute ordering, use plain episode numbers (001, 002, etc.).
Missing Artwork
AniDB has limited poster artwork compared to TMDb. HAMA can be configured to pull artwork from multiple sources — check the agent settings and enable TMDb and TheTVDB as fallback artwork sources.
Duplicate Entries
If the same series appears multiple times, check for inconsistent naming in your files or folders. Plex creates separate entries when it thinks files belong to different series. Standardize folder names and episode numbering, then rescan.
Keeping It Maintained
Anime libraries require more ongoing maintenance than movie or Western TV libraries. New seasons of ongoing series may need folder restructuring, metadata sources update their numbering, and new OVAs or specials need to be placed correctly. Set up Tautulli or the Plex dashboard to catch scan errors, and do a manual review whenever you add content from a series you have not added before.