Build Custom Plex Metadata Agents in Python
Updated November 19, 2026 · PlexBeam
What Are Plex Metadata Agents?
Metadata agents are Python plugins that tell Plex how to identify your media and where to fetch information about it. When Plex scans your library, agents run in a priority chain: each agent tries to match the file to a known title, then fills in metadata like title, year, synopsis, cast, poster artwork, and ratings.
Plex ships with built-in agents for major databases — TheMovieDB, TheTVDB, and the Plex Movie agent (which aggregates multiple sources). But if your library includes niche content like anime from AniDB, adult content, local home videos, educational lectures, or region-specific media, the built-in agents cannot match them. A custom agent lets you fetch metadata from any source: a web API, a local JSON file, a spreadsheet, or a custom database.
Agent Bundle Structure
Plex agents are packaged as "bundles" — directories with a .bundle extension containing a specific file structure:
MyAgent.bundle/
Contents/
Info.plist ← Agent identity and permissions
Code/
__init__.py ← Agent class definition
Libraries/
Shared/ ← Third-party Python libraries
DefaultPrefs.json ← User-configurable preferences
The bundle lives in Plex's plug-ins directory: /var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-ins/ on Linux, or %LOCALAPPDATA%\Plex Media Server\Plug-ins\ on Windows. Plex loads agents on startup and when you restart the Plug-in Support service.
The Info.plist File
The plist declares your agent's identity, the media types it handles, and its permissions. Key fields include:
- CFBundleIdentifier — a unique reverse-domain identifier like
com.yourname.myplexagent - PlexPluginClass — must be
Agentfor metadata agents - PlexClientPlatforms — set to
*to support all client platforms - PlexFrameworkVersion — the Plex Framework API version (currently
2)
Writing the Agent Class
Your agent's Python code lives in __init__.py. The class inherits from Agent.Movies (for movies) or Agent.TV_Shows (for TV) and implements two required methods: search() and update().
The search() Method
Plex calls search(results, media, lang) when it needs to match a file to a metadata entry. The media object contains information extracted from the filename (title, year) and any existing metadata. Your job is to query your data source, find matching entries, and append them to results with a score (0-100) indicating match confidence.
Each result needs at minimum an id (unique identifier in your data source), name (display title), year, score, and lang. Plex sorts results by score and lets the user pick if there are multiple matches.
The update() Method
After a match is selected, Plex calls update(metadata, media, lang) with the matched ID. This is where you fetch the full metadata and populate the metadata object. Available fields include:
metadata.title,metadata.year,metadata.summarymetadata.rating(0.0-10.0),metadata.content_rating(e.g., "PG-13")metadata.studio,metadata.originally_available_at(release date)metadata.genres,metadata.directors,metadata.writers,metadata.roles(cast)metadata.postersandmetadata.art(background images) — these accept URLs or file data
posters and art objects are special proxy containers. Add images with metadata.posters[url] = Proxy.Media(HTTP.Request(url)). Plex downloads and caches the image; your agent does not need to handle image storage.Fetching Data from External APIs
Plex provides a built-in HTTP client through the HTTP and JSON modules. Use JSON.ObjectFromURL(url) to fetch and parse JSON in one call, or HTTP.Request(url) for raw responses. These handle caching, timeouts, and retries automatically.
For APIs that require authentication, store API keys in DefaultPrefs.json as a user-configurable preference. Access them with Prefs['api_key'] in your agent code. Never hardcode credentials in the agent source.
Rate limiting is your responsibility. If your data source has request limits, implement a simple delay between calls or cache responses aggressively. The Plex Framework's HTTP cache (HTTP.CacheTime) is set per-request and defaults to no caching.
Reading Metadata from Local Files
Not all metadata comes from web APIs. For home videos, lectures, or custom collections, you can read metadata from sidecar files (NFO, JSON, or XML) stored alongside your media. Use the media.items[0].parts[0].file path to find the media file, then look for a companion file with the same name but a different extension.
For example, if the media file is /movies/My Film (2024)/My Film (2024).mkv, check for /movies/My Film (2024)/My Film (2024).json. Parse it and populate the metadata object just as you would from an API response.
Agent Priority and Chaining
Plex lets users set agent priority per library. Your custom agent can run first (catching everything it recognizes) with a standard agent as fallback, or it can run after the built-in agents to supplement missing fields. The priority order is configured in Settings → Agents for each library type.
Agents can also contribute partial metadata. If your agent only knows about ratings and genres but not plot summaries, it fills in what it has and the next agent in the chain fills the rest. Set contributes_to in your agent class to declare which primary agents your agent supplements.
Debugging Your Agent
Plex agent logs are your primary debugging tool. They live in the Plex logs directory under PMS Plugin Logs/ in a file named after your bundle identifier. Use Log.Debug(), Log.Info(), and Log.Error() in your agent code to write diagnostic messages.
Common issues when developing agents:
- Agent does not appear in Settings — the Info.plist is malformed or the bundle directory name does not end in
.bundle. Check the main Plex log for plugin load errors. - search() runs but returns no results — your score threshold may be too low or the results list is empty. Add logging before the return to verify what your data source returned.
- Posters do not appear — the image URL is returning a 403 or the proxy call syntax is wrong. Test the URL independently with curl.
- Agent throws ImportError — third-party libraries must be placed in
Contents/Libraries/Shared/and must be pure Python (no compiled C extensions). The Plex Framework runs its own Python interpreter.
.pyc files from your bundle's Code/ directory and restart the Plug-in Support service from Plex settings.Build Better Plex Integrations
PlexBeam covers advanced Plex customization, automation, and infrastructure.
Browse All Guides →