Plex Meta Manager (Kometa): Complete Setup and Configuration

Published 2026-10-16 · PlexBeam

Plex Meta Manager — now called Kometa — is the most powerful tool for automating library organization in Plex. It creates and maintains collections, applies resolution and audio overlays to posters, syncs with external lists from TMDb, IMDb, and Trakt, and keeps everything updated on a schedule. Without Kometa, maintaining a polished, organized library with hundreds of collections requires hours of manual work. With it, you define your rules once in YAML and the tool handles everything automatically.

What Kometa does

Kometa connects to your Plex server and manages metadata, collections, and overlays based on configuration files you write:

  • Automatic collections: Create collections based on any criteria — franchise groupings, genres, decades, studios, actors, directors, ratings, or external lists. Kometa adds and removes items as your library changes, keeping collections current without manual intervention
  • Poster overlays: Add resolution badges (4K, 1080p, 720p), audio format labels (Atmos, DTS-X, TrueHD), HDR indicators, and ratings from IMDb, TMDb, or Rotten Tomatoes directly onto movie and show posters. Users see at a glance what quality and features each title offers
  • External list sync: Sync collections with TMDb lists, IMDb lists, Trakt lists, Letterboxd lists, and more. Create an "Oscar Best Picture Winners" collection that updates automatically when new winners are announced. Sync your Trakt watchlist into a Plex collection for easy access
  • Metadata management: Bulk edit genres, content ratings, labels, and other metadata fields. Standardize genre tags across your library so "Sci-Fi" and "Science Fiction" become one consistent tag

Installation with Docker

Docker is the recommended installation method. It isolates Kometa from your system and makes updates simple:

  • Docker Compose setup: Create a docker-compose.yml with the Kometa image: kometateam/kometa:latest. Mount a local config directory to /config inside the container. Set the timezone environment variable (TZ=America/New_York) so scheduled runs happen at the correct time
  • First run: Start the container. Kometa creates a default config.yml in your config directory. Edit this file to add your Plex server URL, Plex authentication token, and any API keys for external services (TMDb, Trakt, MdbList)
  • Plex token: Find your Plex token by opening any media item in the Plex web app, clicking "Get Info," then "View XML." The token appears in the URL as X-Plex-Token=xxxx. Add this to your config as the token field under your library configuration
  • Alternative: bare metal install: Install Python 3.8+ and clone the Kometa repository. Run with python kometa.py --config /path/to/config.yml. Docker is easier to maintain but bare metal works if Docker is not an option

Configuration structure

The config.yml file is the central configuration. It defines your Plex connection and points to metadata files:

  • Libraries section: Each Plex library gets its own block. Under each library, specify metadata_path (collection definitions), overlay_path (poster overlays), and optional settings like collection_order and minimum_items (hide collections with fewer than this many items)
  • Settings section: Global settings control behavior — run_order (operations, metadata, collections, overlays), sync_mode (append adds items, sync removes items not in the definition), and cache (enable to avoid redundant API calls)
  • API keys: Add API keys for TMDb (free, required for most collection builders), Trakt (free, needed for Trakt lists and watchlists), MdbList (free tier available), and Radarr/Sonarr (optional, for adding missing items to your download queue)
  • Scheduling: Set run_time to control when Kometa runs. A daily run at 3 AM catches new additions and updates collections before anyone wakes up. Multiple run times are supported: run_time: 03:00, 15:00 for twice daily

Building collections with YAML

Collection definitions live in YAML files referenced by your config. Each collection is a block with a name, builder, and optional settings:

  • Smart builders: Use Plex's built-in smart filters: plex_search with criteria like genre, year, rating, resolution, and audio channels. Example: a "4K HDR Movies" collection using plex_search with resolution: 4K and hdr: true automatically includes every 4K HDR title in your library
  • TMDb builders: tmdb_collection pulls franchise groupings directly from TMDb — all Marvel Cinematic Universe films, all James Bond films, all Pixar films. TMDb maintains these lists so your collections stay accurate as new films release. tmdb_list and tmdb_popular pull from curated and trending lists
  • Trakt builders: trakt_list syncs any Trakt list into a Plex collection. trakt_trending and trakt_popular create dynamic collections of currently popular content. trakt_watchlist turns your personal watchlist into a browsable Plex collection
  • IMDb builders: imdb_chart pulls IMDb's Top 250, Most Popular, and other charts. imdb_list syncs any public IMDb list. These collections update automatically as rankings change
  • Combining builders: A single collection can use multiple builders. Combine tmdb_collection with plex_search to create a franchise collection that also includes related specials or documentaries that TMDb does not group together

Setting up overlays

Overlays modify poster images to display useful information at a glance:

  • Resolution overlays: Add a "4K" or "1080p" badge to the corner of each poster based on the file's actual resolution. Users immediately know which titles have high-quality files without opening the detail page. Kometa includes built-in overlay images for common resolutions
  • Audio format overlays: Display "Atmos," "DTS-X," "TrueHD," or "DD 5.1" on posters. Useful for home theater users who want to find content with specific audio formats. Kometa reads the audio track metadata from Plex to determine the correct label
  • Rating overlays: Show IMDb, TMDb, or Rotten Tomatoes scores on posters. Configure the position, size, and style of the rating badge. Multiple ratings can appear on the same poster in different positions
  • Custom overlays: Create your own overlay images for special indicators — an "Unwatched" badge, a "New" indicator for recently added content, or a studio logo. Any PNG image with transparency works as an overlay
  • Overlay reset: Kometa backs up original posters before applying overlays. If you change your overlay configuration, Kometa restores the original poster and applies the new overlay. Never modify poster files outside of Kometa or the backup reference breaks

Scheduling and automation

  • Docker restart policy: Set restart: unless-stopped in your Docker Compose file. Kometa runs at scheduled times and sleeps between runs. The container stays running and handles scheduling internally
  • Run frequency: Daily is sufficient for most libraries. Collections and overlays rarely need updates more than once per day. If you add media frequently through Sonarr and Radarr, twice daily catches new additions faster
  • Partial runs: Use the --collections-only or --overlays-only flag to run only part of the configuration. Useful for testing new collections without waiting for the full overlay process to complete
  • Notifications: Configure webhook notifications to Discord or other services when Kometa completes a run. See which collections were updated, how many items were added or removed, and whether any errors occurred

Common mistakes and troubleshooting

  • YAML indentation: YAML is whitespace-sensitive. Use spaces, never tabs. Each nesting level is exactly two spaces. A misplaced space or tab causes the entire file to fail to parse. Use a YAML validator before saving changes
  • Sync mode confusion: sync_mode: sync removes items from a collection if they no longer match the builder criteria. sync_mode: append only adds items, never removes. Use sync for dynamic collections and append for curated collections where you manually add items alongside automated ones
  • API rate limits: TMDb limits free API usage. If you have hundreds of collections all querying TMDb, Kometa may hit rate limits and fail partway through. Enable caching in config.yml to reduce API calls on subsequent runs
  • Overlay conflicts: Multiple overlays in the same position overlap and become unreadable. Assign each overlay type a unique position — resolution in the top-left, audio in the top-right, ratings in the bottom-left. Plan your layout before configuring overlays
  • Missing items: If a collection should include a title but does not, check that the title's metadata in Plex matches the builder criteria. Genre tags, years, and ratings must be correct in Plex for smart filters to work. Run a metadata refresh on problem titles
← Back to Blog
More from LuxuriousComputers: LuxuriousComputers · Computer Repair · Remote Fix · Phone Repair · HVAC · Plex Support