← Back to Blog

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:

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:

Important: The 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:

Pro Tip: During development, restart just the agent (not the entire Plex server) by deleting the agent's compiled Python cache: remove all .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 →

Related Articles

More from LuxuriousComputers: LuxuriousComputers · Computer Repair · Remote Fix · Phone Repair · HVAC · Plex Support