Skip to content

Kometa Setup Guide

Andy Gillis edited this page Nov 17, 2026 · 3 revisions

Kometa Setup Guide

Introduction

Kometa (formerly Plex Meta Manager) builds and maintains collections in Plex automatically: franchises in watch order, "Trending this week", Oscar winners, Christmas movies in December, and so on. It can also add overlays (badges) to posters, such as resolution, HDR or Rotten Tomatoes scores, so you see them while browsing instead of opening each title.

It's most valuable when your household browses Plex rather than searching.

Read this first: protect your Plex database. Kometa makes thousands of changes through Plex's API. A heavy first run (every library, overlays and playlists at once) on a slow NAS can corrupt Plex's database badly enough that it can't be recovered, and rebuilding it loses everyone's watch history. Start small, back up first, and grow one step at a time. The steps below are built around that.

How It's Set Up Here

  • Runs on a desktop, not the NAS (compose/server2/kometa.yaml). Kometa talks to Plex over the network, and the heavy part (building overlay images) uses that machine's CPU.
  • Runs at 00:30, finishing before Plex's own nightly maintenance (from 02:00), so the two never write to the database at the same time.
  • If that machine is off, that night's run is skipped; collections stay as they are.
services:
  kometa:
    container_name: kometa.${HOST_NAME}
    image: kometateam/kometa:latest
    environment:
      TZ: ${TZ}
      KOMETA_TIMES: "00:30"            # run time(s); Kometa ignores CRON
      KOMETA_CONFIG: /config/config.yml
    volumes:
      - ${DOCKERDIR}/kometa/config:/config
    restart: unless-stopped

Step 1: Back Up the Plex Database

Plex keeps its own backups (Settings → Scheduled Tasks → Backup database every three days; leave it on). Before Kometa's first run, and before each big step up, also make a copy you know is good, using Plex's bundled SQLite while Plex is running:

docker exec plex.<host> sh -c '
cd "/config/Plex Media Server/Plug-in Support/Databases"
S="/usr/lib/plexmediaserver/Plex SQLite"
for db in com.plexapp.plugins.library.db com.plexapp.plugins.library.blobs.db; do
  "$S" "$db" ".backup \"$db-before-kometa\""
  "$S" "$db-before-kometa" "PRAGMA quick_check;"   # should print: ok
done'

(The path inside the container depends on your Plex image.)

Step 2: Config

appdata/kometa/config/config.yml (keep it out of git; it holds your Plex token and TMDb key):

plex:
  url: http://192.168.1.10:32400
  token: <your Plex token>
tmdb:
  apikey: <free key from themoviedb.org>
  language: en

libraries:
  Movies:
    collection_files:
      - default: basic        # Newly Released, Recently Added
      - default: tmdb         # Trending, Popular, Top Rated
      - default: imdb         # IMDb Top 250, Popular
      - default: franchise    # franchises in release order
      - default: seasonal     # Christmas, Halloween... shown in season
      - default: decade
      - default: oscars

settings:
  run_order:
  - collections
  cache: true
  sync_mode: append
  minimum_items: 1
  delete_below_minimum: true

Start with one library and collections only: no overlay_files, no playlist_files, no operations.

Step 3: Test, Then Let It Run

A test run connects to Plex and TMDb and checks the config, but only builds collections marked test: true (none, here):

docker compose -p mediaserver -f docker-compose-server2.yaml run --rm kometa --run --tests

Look for TMDb Connection Successful and Movies Library Connection Successful.

On the very first run you'll see thousands of No TMDb ID for Guid: plex://movie/... lines. That's normal: they appear before Kometa has built its ID cache, and later in the same run it matches the movies (Cache | + | plex://movie/... | TMDb ID: ...). From then on the cache is used.

Then leave it to its schedule, and read the log after the first night: appdata/kometa/config/logs/meta.log.

Step 4: Grow It Gradually

After a few clean nights, add one thing at a time, backing up the database before each:

  1. Rotten Tomatoes scores on posters (critic and audience):
        overlay_files:
          - default: ratings
            template_variables:
              rating1: critic
              rating1_image: rt_tomato
              rating2: audience
              rating2_image: rt_popcorn
    Overlays replace each poster with a badged version. Kometa keeps the original so remove_overlays: true can put it back.
  2. TV collections, then TV overlays.
  3. Other libraries (animated, music) last.

Troubleshooting

  • Connection refused to Plex: use the server's LAN IP and port 32400, not a domain behind Cloudflare Access.
  • Run takes hours: that's usually overlays on a big library; keep them to the libraries where you want them.
  • Collections disappeared: delete_below_minimum: true removes collections that drop below minimum_items, and seasonal collections hide out of season. Both are expected.
  • Plex feels slow during the run: move the run time further from busy hours, and keep it out of Plex's maintenance window.

Clone this wiki locally