Overview

Kometa is a Python script that takes control of a Plex library and rewrites the parts Plex leaves to you: artwork, titles, summaries, collections and overlays. It reads YAML files that describe what you want — “make a collection of every film in the IMDb Top 250”, “put a 4K badge on anything that is 2160p”, “rename this show the way I like it” — and then applies those rules to the library through the Plex API, on a schedule you set.

It is the project formerly known as Plex Meta Manager, now maintained by the Kometa-Team and released under the MIT licence. Third-party metadata comes from services such as TMDb and IMDb, and the project ships pre-made “defaults” files, so most libraries can get curated collections and overlay sets without writing the YAML from scratch. It is not a Plex replacement and not a media server: it is the automation layer that keeps an existing Plex library tidy, themed and consistent.

Key Features

• Collections from external data: build Plex collections from TMDb and IMDb lists and charts, or from your own filters, and keep them updated on a schedule instead of by hand.
• Overlays on posters: burn badges onto artwork — resolution, HDR and Dolby Vision, audio format, ratings, network, language — so a library is readable at a glance without opening a single item.
• Metadata rewriting: change titles, sort titles, summaries, content ratings, studio and artwork for individual items or whole libraries, using the same rule files.
• Pre-made defaults: the project publishes a large library of ready-made collection and overlay files, which you enable and point at your own libraries rather than authoring everything yourself.
• Arr integration: talks to Sonarr and Radarr (and the rest of the family) so collections and metadata follow what those tools add to the library.
• YAML configuration with validation: a single config.yml plus optional collection, overlay, metadata and playlist files, all checkable without touching the library using the built-in config validation mode.
• Scheduling: per-library run schedules with several modes, so a large library can be kept current incrementally instead of rescanned in full every night.
• Docker-first deployment: the official kometateam/kometa image is the documented way to run it, with native Python 3.11+ as the alternative.

Why Use Kometa

Plex will organise what you own, but it will not curate it. Collections that track a chart, poster badges that show which films are 4K, consistent artwork across a library — all of that is manual work, and it rots the moment new media arrives. Kometa turns those wishes into files that are re-applied on a schedule, so the library keeps the shape you gave it. The YAML is versionable and the defaults make the first win cheap: enable one collection file, run it once, and the library changes.

Typical Uses

• Keeping chart-driven collections (IMDb Top 250, Oscar winners, seasonal and genre sets) current in a large film library.
• Adding resolution, HDR and audio badges to posters so the library can be browsed without opening items.
• Normalising artwork, titles and summaries across a library assembled from several sources over the years.
• Growing collections automatically from what Sonarr and Radarr add, without a second manual pass.

Getting Started

The documented route is Docker: pull kometateam/kometa, mount a config directory, and put a config.yml in it with the Plex URL and token plus one entry per library. Point the library at a collection or overlay file — the project’s defaults are the fastest start — and run it once by hand to see the result before putting it on a schedule. The --validate-config mode checks the YAML and everything it includes without writing to Plex, which is the safe way to iterate on rules. Native installs need Python 3.11 or newer and the dependencies in the repository.