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.ymlwith the Kometa image:kometateam/kometa:latest. Mount a local config directory to/configinside 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.ymlin 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 thetokenfield 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 likecollection_orderandminimum_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), andcache(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_timeto 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:00for 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_searchwith criteria like genre, year, rating, resolution, and audio channels. Example: a "4K HDR Movies" collection usingplex_searchwithresolution: 4Kandhdr: trueautomatically includes every 4K HDR title in your library - TMDb builders:
tmdb_collectionpulls 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_listandtmdb_popularpull from curated and trending lists - Trakt builders:
trakt_listsyncs any Trakt list into a Plex collection.trakt_trendingandtrakt_popularcreate dynamic collections of currently popular content.trakt_watchlistturns your personal watchlist into a browsable Plex collection - IMDb builders:
imdb_chartpulls IMDb's Top 250, Most Popular, and other charts.imdb_listsyncs any public IMDb list. These collections update automatically as rankings change - Combining builders: A single collection can use multiple builders. Combine
tmdb_collectionwithplex_searchto 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-stoppedin 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-onlyor--overlays-onlyflag 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: syncremoves items from a collection if they no longer match the builder criteria.sync_mode: appendonly adds items, never removes. Usesyncfor dynamic collections andappendfor 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.ymlto 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