Skip to content

Run Commands & Environment Variables

What does it mean to run Kometa?

Starting Kometa and running your configuration are separate steps. By default, Kometa waits until 5:00 AM, processes your configuration, then waits until the same time the next day. Add --run to process your configuration immediately and exit when finished.

Processing your configuration means carrying out the collection, metadata, overlay, playlist, and library tasks you have configured. In this documentation and on Discord, a "run" refers to this processing step.

Start Kometa with its default schedule:

uv run python kometa.py

docker run --rm -it -v "/<ROOT_KOMETA_DIRECTORY_HERE>/config:/config:rw" kometateam/kometa

To run immediately and exit:

uv run python kometa.py --run

docker run --rm -it -v "/<ROOT_KOMETA_DIRECTORY_HERE>/config:/config:rw" kometateam/kometa --run

Customize runtime behavior

The options below are optional. Use them to change how Kometa runs, including overriding supported settings without editing your configuration file. If you do not set an option, Kometa uses its default behavior or the applicable configuration setting.

Each option lists its command-line flags and environment variable:

  • Command-line flags are added to the command that starts Kometa, such as --run.
  • Environment variables are values Kometa reads when it starts. Set them in your shell, a script, your Docker container, or a .env file.

Local examples use uv run from your Kometa checkout, following the local installation guide. These examples assume familiarity with command-line tools and, for container installations, Docker.

Which value takes precedence?

Environment variables take precedence over command-line flags. For example:

export KOMETA_CONFIG=/path/to/environment/config.yml
uv run python kometa.py --config /path/to/runtime-var/config.yml

Kometa uses /path/to/environment/config.yml because KOMETA_CONFIG overrides --config.

Save options in a .env file

To reuse several environment variables across runs, add them to a .env file in your config folder:

KOMETA_CONFIG=/path/to/your-config-file.yml
KOMETA_TIMES=06:00|18:00
KOMETA_TRACE=true
KOMETA_LOG_REQUESTS=true
KOMETA_TIMEOUT=360
KOMETA_NO_VERIFY_SSL=true
KOMETA_COLLECTIONS_ONLY=true

Choose the variables you need from the reference below. Kometa loads the file at startup, so you do not need to set those variables manually for every run.

Combining Commands or Variables

Some Commands or Variables can be combined in a single run, this is mainly beneficial when you want to run a specific command and have it run immediately rather than waiting until the next scheduled run.

For example, if I want to run Collections Only to only run Collection Files, and Run Immediately to skip waiting until my next scheduled run, I can use both commands at the same time:

Example

uv run python kometa.py --collections-only --run

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --collections-only --run

All available runtime flags/environment variables

Configuration and scheduling

Config Location · -c/--config · KOMETA_CONFIG

Kometa looks for its config file at config/config.yml. If you want to change that, perhaps to use a special-purpose config.yml or the like, you can use this flag to specify the location of the configuration YAML file.

Accepted Values: Path to YAML config file

Shell Flags: -c or --config (ex. --config /some/path/to/your-config-file.yml)

Environment Variable: KOMETA_CONFIG (ex. KOMETA_CONFIG=/some/path/to/your-config-file.yml)

Example

uv run python kometa.py --config /some/path/to/your-config-file.yml

docker run -it -v "X:\Media\Kometa\config:/config:rw" -v "Z:\some\path:/data:rw" kometateam/kometa --config /data/your-config-file.yml
Time to Run · -t/--times · KOMETA_TIMES

Kometa wakes up at 5:00 AM to process the config file. If you want to change that time, or tell Kometa to wake up at multiple times, use this flag.

Accepted Values: Pipe-separated list in HH:MM format

Shell Flags: -t or --times (ex. --times "06:00|18:00")

Environment Variable: KOMETA_TIMES (ex. KOMETA_TIMES=06:00|18:00)

Example

uv run python kometa.py --times '22:00|03:00'

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --times "22:00|03:00"
Run Immediately · -r/--run · KOMETA_RUN

If you want Kometa to run immediately rather than waiting until 5AM, set this flag to true.

Shell Flags: -r or --run (ex. --run)

Environment Variable: KOMETA_RUN (ex. KOMETA_RUN=true)

Example

uv run python kometa.py --run

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --run
Resume Run · -re/--resume · KOMETA_RESUME

Perform an immediate run starting from the first instance of the specified collection, bypassing the time to run flag.

Shell Flags: -re or --resume (ex. --resume "Star Wars")

Environment Variable: KOMETA_RESUME (ex. KOMETA_RESUME=Star Wars)

Example

uv run python kometa.py --resume "Star Wars"

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --resume "Star Wars"
Ignore Schedules · -is/--ignore-schedules · KOMETA_IGNORE_SCHEDULES

Ignore all schedules for the run. Range Scheduled collections (such as Christmas movies) will still be ignored.

Shell Flags: -is or --ignore-schedules (ex. --ignore-schedules)

Environment Variable: KOMETA_IGNORE_SCHEDULES (ex. KOMETA_IGNORE_SCHEDULES=true)

Example

uv run python kometa.py --ignore-schedules

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --ignore-schedules
Read Only Config · -ro/--read-only-config · KOMETA_READ_ONLY_CONFIG

Kometa reads in and then writes out a properly formatted version of your config.yml on each run;this makes the formatting consistent and ensures that you have visibility into new settings that get added. If you want to disable this behavior and tell Kometa to leave your config.yml as-is, use this flag.

Shell Flags: -ro or --read-only-config (ex. --read-only-config)

Environment Variable: KOMETA_READ_ONLY_CONFIG (ex. KOMETA_READ_ONLY_CONFIG=true)

Example

uv run python kometa.py --read-only-config

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --read-only-config
Config Secrets · --kometa-*** · KOMETA_***

All Run Commands that are in the format --kometa-*** and Environment Variables that are in the format KOMETA_***, where *** is the name you want to call the variable, will be loaded in as Config Secrets.

These Config Secrets can be loaded into the config by placing <<***>> in any field in the config, where *** is whatever name you called the variable.

Shell Flags: --kometa-*** (ex. --kometa-mysecret 123456789)

Environment Variable: KOMETA_*** (ex. KOMETA_MYSECRET=123456789)

Example

uv run python kometa.py --kometa-mysecret 123456789

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --kometa-mysecret 123456789

Example Config Usage:

tmdb:
  apikey: <<mysecret>>

IMPORTANT: DO NOT use underscores in the secret name. <<mysecret>> works, <<my_secret>> will not.

Choose what runs

Collections Only · -co/--collections-only · KOMETA_COLLECTIONS_ONLY

Only run collection YAML files, skip library operations, metadata, overlays, and playlists.

Shell Flags: -co or --collections-only (ex. --collections-only)

Environment Variable: KOMETA_COLLECTIONS_ONLY (ex. KOMETA_COLLECTIONS_ONLY=true)

Example

uv run python kometa.py --collections-only

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --collections-only

IMPORTANT: only one of these --SOMETHING-only flags can be active at one time. If you enable more than one, like perhaps one as an env var and one as a runtime flag, Kometa will exit early with an error.

Metadata Only · -mo/--metadata-only · KOMETA_METADATA_ONLY

Only run metadata files, skip library operations, collections, overlays, and playlists.

Shell Flags: -mo or --metadata-only (ex. --metadata-only)

Environment Variable: KOMETA_METADATA_ONLY (ex. KOMETA_METADATA_ONLY=true)

Example

uv run python kometa.py --metadata-only

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --metadata-only

IMPORTANT: only one of these --SOMETHING-only flags can be active at one time. If you enable more than one, like perhaps one as an env var and one as a runtime flag, Kometa will exit early with an error.

Playlists Only · -po/--playlists-only · KOMETA_PLAYLISTS_ONLY

Only run playlist YAML files, skip library operations, overlays, collections, and metadata.

Shell Flags: -po or --playlists-only (ex. --playlists-only)

Environment Variable: KOMETA_PLAYLISTS_ONLY (ex. KOMETA_PLAYLISTS_ONLY=true)

Example

uv run python kometa.py --playlists-only

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --playlists-only

IMPORTANT: only one of these --SOMETHING-only flags can be active at one time. If you enable more than one, like perhaps one as an env var and one as a runtime flag, Kometa will exit early with an error.

Operations Only · -op/--operations-only · KOMETA_OPERATIONS_ONLY

Only run library operations skipping collections, metadata, playlists, and overlays.

Shell Flags: -op or --operations-only (ex. --operations-only)

Environment Variable: KOMETA_OPERATIONS_ONLY (ex. KOMETA_OPERATIONS_ONLY=true)

Example

uv run python kometa.py --operations-only

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --operations-only

IMPORTANT: only one of these --SOMETHING-only flags can be active at one time. If you enable more than one, like perhaps one as an env var and one as a runtime flag, Kometa will exit early with an error.

Overlays Only · -ov/--overlays-only · KOMETA_OVERLAYS_ONLY

Only run library overlay files skipping collections, metadata, playlists, and operations.

Shell Flags: -ov or --overlays-only (ex. --overlays-only)

Environment Variable: KOMETA_OVERLAYS_ONLY (ex. KOMETA_OVERLAYS_ONLY=true)

Example

uv run python kometa.py --overlays-only

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --overlays-only

IMPORTANT: only one of these --SOMETHING-only flags can be active at one time. If you enable more than one, like perhaps one as an env var and one as a runtime flag, Kometa will exit early with an error.

Run Collections · -rc/--run-collections · KOMETA_RUN_COLLECTIONS

Perform an immediate run to run only the named collections, bypassing the time to run flag.

Accepted Values: Pipe-separated list of Collection Names to run; the "pipe" character is "|" as shown in the examples below.

Shell Flags: -rc or --run-collections (ex. --run-collections "Harry Potter|Star Wars")

Environment Variable: KOMETA_RUN_COLLECTIONS (ex. KOMETA_RUN_COLLECTIONS=Harry Potter|Star Wars)

Example

uv run python kometa.py --run-collections "Harry Potter|Star Wars"

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --run-collections "Harry Potter|Star Wars"
Run Libraries · -rl/--run-libraries · KOMETA_RUN_LIBRARIES

Perform an immediate run to run only the named libraries, bypassing the time to run flag.

Accepted Values: Pipe-separated list of Library Names to run; the "pipe" character is "|" as shown in the examples below.

Shell Flags: -rl or --run-libraries (ex. --run-libraries "Movies - 4K|TV Shows - 4K")

Environment Variable: KOMETA_RUN_LIBRARIES (ex. KOMETA_RUN_LIBRARIES=Movies - 4K|TV Shows - 4K)

Example

uv run python kometa.py --run-libraries "Movies - 4K|TV Shows - 4K"

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --run-libraries "Movies - 4K|TV Shows - 4K"
Run Files · -rf/--run-files · KOMETA_RUN_FILES

Perform an immediate run to run only the named Collection, Metadata or Playlist files, bypassing the time to run flag. This works for all different paths i.e. default, git, url, file, or repo.

Warning

Do not use this to run Overlay files, as Overlay files must run all together or not at all due to their nature.

Accepted Values: Pipe-separated list of Collection, Metadata or Playlist Filenames to run; the "pipe" character is "|" as shown in the examples below.

Shell Flags: -rf or --run-files (ex. --run-files "Movies.yml|MovieCharts")

Environment Variable: KOMETA_RUN_FILES (ex. KOMETA_RUN_FILES=Movies.yml|MovieCharts)

Example

uv run python kometa.py --run-files "Movies.yml|MovieCharts"

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --run-files "Movies.yml|MovieCharts"
Run Mode · --mode · KOMETA_MODE

Set the library schedule mode for every library in this run. This overrides configured library schedule modes, including libraries without a matching schedule. Other schedule rules still apply.

Best practices and examples

See the Scheduling Kometa and Library Runs guide for the best practices and some examples of how to use --mode effectively against your server.

Shell Flag: --mode (ex. --run --mode 'items(imdb:tt1232829|tmdb:187017)')

Environment Variable: KOMETA_MODE (ex. KOMETA_MODE=added(7))

Mode What it does Example command
full Processes every top-level item in each library. uv run python kometa.py --run --mode full
items(ids) Processes only the listed items. Separate IDs with a pipe character. Movies match TMDb IDs, shows match TVDb IDs, and TMDb show IDs are converted to TVDb IDs. IMDb IDs and top-level Plex rating keys work for either. uv run python kometa.py --run --mode 'items(imdb:tt0133093)'
added(duration) Processes items added to Plex within the last duration. Use a positive integer with m (minutes), h (hours), or d (24-hour days); a bare integer means days. For shows, it also includes shows with recently added episodes. uv run python kometa.py --run --mode 'added(30m)'
diff Processes items missing from Kometa's previous library cache snapshot. For shows, it compares each season's Plex update time. Requires a persistent Kometa cache. uv run python kometa.py --run --mode diff
index(A-Z) Processes titles whose first letter is in the inclusive A through Z range. Uses the Plex Sort Title when available. uv run python kometa.py --run --mode 'index(A-F)'
index(A-Z#) Processes the A through Z range plus titles beginning with a number or symbol. uv run python kometa.py --run --mode 'index(A-F#)'

Replace the IDs with those of items in your library. To select multiple items, use a pipe between IDs, for example uv run python kometa.py --run --mode 'items(imdb:tt0133093|tmdb:550|tvdb:350396|plex:42)'. Keep the single quotes around modes containing parentheses when using PowerShell. See Library Schedule Modes for identifier and matching details.

Ignore Ghost · -ig/--ignore-ghost · KOMETA_IGNORE_GHOST

Kometa prints some things to the log that don't actually go into the log file on disk. Typically these are things like status messages while loading and/or filtering. If you want to hide all ghost logging for the run, use this flag.

Shell Flags: -ig or --ignore-ghost (ex. --ignore-ghost)

Environment Variable: KOMETA_IGNORE_GHOST (ex. KOMETA_IGNORE_GHOST=true)

Example

uv run python kometa.py --ignore-ghost

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --ignore-ghost
Run Tests · -ts/--tests · KOMETA_TESTS

If you set this flag to true, Kometa will run only collections that you have marked as test immediately, as KOMETA_RUN.

NOTE: This will only run collections with test: true in the definition.

Shell Flags: -ts or --tests (ex. --tests)

Environment Variable: KOMETA_TESTS (ex. KOMETA_TESTS=true)

Example

uv run python kometa.py --tests

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --tests

In my collection YAML file, I would set true: false like this:

collections:
  Marvel Cinematic Universe:
    test: true                  # HERE
    mdblist_list: mdblist_list: https://mdblist.com/lists/stealthgyro/marvel-cinematic-universe-mcu
    smart_label: release.desc

Diagnostics and logging

Debug · -db/--debug · KOMETA_DEBUG

To show debug messages in the command window or Docker console output, set this flag to true. Detailed log files such as meta.log include debug messages regardless of this setting so they retain the diagnostic information needed for troubleshooting.

Shell Flags: -db or --debug (ex. --debug)

Environment Variable: KOMETA_DEBUG (ex. KOMETA_DEBUG=true)

Example

uv run python kometa.py --debug

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --debug
Trace · -tr/--trace · KOMETA_TRACE

To increase the verbosity of the logs even more than debug, set this flag to true.

Trace logs include a message before each Plex request with its method, item path, and configured timeout, followed by completion or failure and elapsed time. If a run appears stuck, a Plex request starting line without a matching completion or failure identifies the pending query. Query parameters, headers, and request bodies are omitted. The timeout applies to connection and read operations; it is not a total request deadline.

Shell Flags: -tr or --trace (ex. --trace)

Environment Variable: KOMETA_TRACE (ex. KOMETA_TRACE=true)

Example

uv run python kometa.py --trace

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --trace
Log Requests · -lr/--log-requests · KOMETA_LOG_REQUESTS

If you enable this, every external network request made by Kometa will be logged, along with the data that is returned. This will add a lot of data to the logs, and will probably contain things like tokens, since the auto-redaction of such things is not generalized enough to catch any token that may be in any URL.

This can potentially have personal information in it.

Shell Flags: -lr or --log-requests (ex. --log-requests)

Environment Variable: KOMETA_LOG_REQUESTS (ex. KOMETA_LOG_REQUESTS=true)

Example

uv run python kometa.py --log-requests

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --log-requests
Timing Instrumentation · --timings/--timing · KOMETA_TIMINGS

Run with lightweight timing instrumentation enabled. Kometa times network calls, cache lookups, and major per-collection/per-library phases, then prints a summary to the log at the end of the run and exports a full per-source/per-library breakdown as JSON and CSV files to the logs directory.

Disabled by default, with negligible overhead when off.

Shell Flags: --timings or --timing (ex. --timings)

Environment Variable: KOMETA_TIMINGS or KOMETA_TIMING (ex. KOMETA_TIMINGS=true)

Example

uv run python kometa.py --run --timings

docker run -it -v "X:\Media\Kometa\config:/config:rw" -e KOMETA_TIMINGS=true kometateam/kometa --run
Source Integrity · --source-integrity/--no-source-integrity · KOMETA_SOURCE_INTEGRITY

Check distributed Kometa files against official source for the exact installed commit. Enabled by default; checking waits up to 30 seconds during startup and never prevents Kometa from running. Results appear with the startup system information, with no integrity messages during library processing. The end-of-run summary repeats the startup result. See Source integrity for states, caching, and exclusions.

Shell Flags: --source-integrity enables checking; --no-source-integrity disables it.

Environment Variable: KOMETA_SOURCE_INTEGRITY (ex. KOMETA_SOURCE_INTEGRITY=false). Environment variables take precedence over CLI flags.

Example

uv run python kometa.py --run --no-source-integrity

docker run -it -v "X:\Media\Kometa\config:/config:rw" -e KOMETA_SOURCE_INTEGRITY=false kometateam/kometa --run
Deep Profiling · KOMETA_PROFILE

Run a single Kometa run under pyinstrument, writing an HTML profile report to the logs directory. Intended for maintainers diagnosing a specific slow run in more depth than Timing Instrumentation's summary provides.

Environment Variable: KOMETA_PROFILE set to pyinstrument (ex. KOMETA_PROFILE=pyinstrument)

Example

KOMETA_PROFILE=pyinstrument uv run python kometa.py --run

docker run -it -v "X:\Media\Kometa\config:/config:rw" -e KOMETA_PROFILE=pyinstrument kometateam/kometa --run
No Countdown · -nc/--no-countdown · KOMETA_NO_COUNTDOWN

Typically, when not doing an immediate run, Kometa displays a countdown in the terminal where it's running. If you want to hide this countdown, use this flag.

Shell Flags: -nc or --no-countdown (ex. --no-countdown)

Environment Variable: KOMETA_NO_COUNTDOWN (ex. KOMETA_NO_COUNTDOWN=true)

Example

uv run python kometa.py --no-countdown

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --no-countdown
Divider Character · -d/--divider · KOMETA_DIVIDER

The log is split into sections with lines of =. If you wish to change that character to a different one, you can do that with this flag.

Accepted Values: Any character

Shell Flags: -d or --divider (ex. --divider *)

Environment Variable: KOMETA_DIVIDER (ex. KOMETA_DIVIDER=*)

Example

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --divider *
uv run python kometa.py --divider *
Screen Width · -w/--width · KOMETA_WIDTH

The log is formatted to fit within a certain width. If you wish to change that width, you can do that with this flag. Not that long lines are not wrapped or truncated to this width; this controls the minimum width of the log.

Accepted Values: Integer between 90 and 300

Shell Flags: -w or --width (ex. --width 150)

Environment Variable: KOMETA_WIDTH (ex. KOMETA_WIDTH=150)

Example

uv run python kometa.py --width 150

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --width 150

Connections and process settings

Timeout · -ti/--timeout · KOMETA_TIMEOUT

Change the timeout in seconds for all non-Plex services (such as TMDb and Radarr). This will default to 180 when not specified and is overwritten by any timeouts mentioned for specific services in the Configuration File.

Accepted Values: Integer (value is in seconds)

Shell Flags: -ti or --timeout (ex. --timeout 360)

Environment Variable: KOMETA_TIMEOUT (ex. KOMETA_TIMEOUT=360)

Example

uv run python kometa.py --timeout 360

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --timeout 360
No Verify SSL · -nv/--no-verify-ssl · KOMETA_NO_VERIFY_SSL

Turn SSL Verification off.

Note

set to false if your log file shows any errors similar to "SSL: CERTIFICATE_VERIFY_FAILED"

IMPORTANT: This will disable TLS checks for all outbound services (TMDb, MAL, etc.). Only flip this switch if you are comfortable with this.

Shell Flags: -nv or --no-verify-ssl (ex. --no-verify-ssl)

Environment Variable: KOMETA_NO_VERIFY_SSL (ex. KOMETA_NO_VERIFY_SSL=true)

Example

uv run python kometa.py --no-verify-ssl

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --no-verify-ssl
Priority · -lp/--low-priority · KOMETA_LOW_PRIORITY

Run the Kometa process at a lower priority. Will default to normal priority if not specified.

Shell Flags: -lp or --low-priority (ex. --low-priority)

Environment Variable: KOMETA_LOW_PRIORITY (ex. KOMETA_LOW_PRIORITY=true)

Example

uv run python kometa.py --low-priority

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --low-priority

Missing items and reports

No Missing · -nm/--no-missing · KOMETA_NO_MISSING

Kometa can take various actions on missing items, such as sending them to Radarr, listing them in the log, or saving a report. If you want to disable all of these actions, use this flag.

Shell Flags: -nm or --no-missing (ex. --no-missing)

Environment Variable: KOMETA_NO_MISSING (ex. KOMETA_NO_MISSING=true)

Example

uv run python kometa.py --no-missing

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --no-missing
No Report · -nr/--no-report · KOMETA_NO_REPORT

Kometa can produce a report of missing items, collections, and other information. If you have this report enabled but want to disable it for a specific run, use this flag.

Shell Flags: -nr or --no-report (ex. --no-report)

Environment Variable: KOMETA_NO_REPORT (ex. KOMETA_NO_REPORT=true)

Example

uv run python kometa.py --no-report

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --no-report

Cleanup

Delete Collections · -dc/--delete-collections · KOMETA_DELETE_COLLECTIONS

Delete all collections in each library as the first step in the run.

Warning

You will lose all collections in the library - this will delete all collections, including ones not created or maintained by Kometa.

Shell Flags: -dc or --delete-collections (ex. --delete-collections)

Environment Variable: KOMETA_DELETE_COLLECTIONS (ex. KOMETA_DELETE_COLLECTIONS=true)

Example

uv run python kometa.py --delete-collections

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --delete-collections
Delete Labels · -dl/--delete-labels · KOMETA_DELETE_LABELS

Delete all labels [save one, see below] on every item in a Library prior to running collections/operations.

Warning

To preserve functionality of Kometa, this will not remove the Overlay label, which is required for Kometa to know which items have Overlays applied.

This will impact any Smart Label Collections that you have in your library. We do not recommend using this on a regular basis if you also use any operations or collections that update labels, as you are effectively deleting and adding labels on each run.

Shell Flags: -dl or --delete-labels (ex. --delete-labels)

Environment Variable: KOMETA_DELETE_LABELS (ex. KOMETA_DELETE_LABELS=true)

Example

uv run python kometa.py --delete-labels

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --delete-labels
Delete Collections + Labels · --delete-collections-labels · KOMETA_DELETE_COLLECTIONS_LABELS

Delete all collections in each library as the first step in the run, same as Delete Collections above. For any deleted collection whose title matches an existing Plex label of the same name - the default for Smart Label Collections - also batch-removes that one label from just the items that currently have it, instead of the full library-wide label wipe Delete Labels does.

Note

This only detects Smart Label collections using the default label name (the collection's own title). A collection using a custom smart_label name won't be matched, since that name isn't known until the config is parsed - use Delete Labels for those.

This flag has no short form - -dc and -dl are single-dash because they're exactly 2 characters (Kometa's own convention for short flags); anything longer would collide with an existing single-character flag (e.g. -d/--divider) when typed with a single dash. Use --delete-collections-labels or --delete-collection-label in full.

Shell Flags: --delete-collections-labels or --delete-collection-label (ex. --delete-collections-labels)

Environment Variable: KOMETA_DELETE_COLLECTIONS_LABELS (ex. KOMETA_DELETE_COLLECTIONS_LABELS=true)

Example

uv run python kometa.py --delete-collections-labels

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --delete-collections-labels

Validation

Validate Config · -va/--validate-config · KOMETA_VALIDATE

Parse and validate config.yml and all YAML files linked from it, print a structured report, then exit — without performing a normal run.

Exits with code 0 if validation passes, 1 if there are any errors. Warnings do not affect the exit code.

Use --validate-level to control how deep the validation goes. Combine with --validate-schema to also check files against their JSON schemas.

Shell Flags: -va, --validate-config, or --validate (ex. --validate)

Environment Variable: KOMETA_VALIDATE (ex. KOMETA_VALIDATE=true)

Example

uv run python kometa.py --validate

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --validate
Validate Level · -vl/--validate-level · KOMETA_VALIDATE_LEVEL

Controls how deep the validation goes when --validate is set. Default is structure.

Level What it checks
syntax Parses config.yml and all linked local YAML files; reports any YAML syntax errors. Remote references (url:, git:, default:, repo:) are skipped.
structure Everything in syntax, plus: checks for required keys (libraries, tmdb), warns on deprecated keys (metadata_path, overlay_path), and errors on local file: paths that don't exist on disk.
full Calls the full Kometa config initialisation (connects to Plex and all configured APIs) without actually running any collections, overlays, or operations.

Accepted Values: syntax, structure, or full

Shell Flags: -vl or --validate-level (ex. --validate-level syntax)

Environment Variable: KOMETA_VALIDATE_LEVEL (ex. KOMETA_VALIDATE_LEVEL=syntax)

Example

uv run python kometa.py --validate --validate-level syntax

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --validate --validate-level syntax
Validate Schema · -vs/--validate-schemas · KOMETA_VALIDATE_SCHEMA

When set alongside --validate, each YAML file is also checked against its corresponding JSON schema in the json-schema/ directory.

Schema violations are split into two categories:

  • Errors — type mismatches, failed required checks, and other constraint violations. These cause exit code 1.
  • Schema gaps — keys found in your files that are not defined in the schema (additionalProperties violations). These are reported separately as a gap report and do not affect the exit code. They are useful for identifying where the JSON schemas need to be extended.

Shell Flags: -vs, --validate-schemas, or --validate-schema (ex. --validate-schema)

Environment Variable: KOMETA_VALIDATE_SCHEMA (ex. KOMETA_VALIDATE_SCHEMA=true)

Example

uv run python kometa.py --validate --validate-schema

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --validate --validate-schema
Schema Path · -sp/--schema-path · KOMETA_SCHEMA_PATH

Override the path to the json-schema/ directory used by --validate-schema. Defaults to the json-schema/ folder next to kometa.py.

Accepted Values: Path to a directory containing JSON schema files

Shell Flags: -sp or --schema-path (ex. --schema-path /some/path/to/json-schema)

Environment Variable: KOMETA_SCHEMA_PATH (ex. KOMETA_SCHEMA_PATH=/some/path/to/json-schema)

Example

uv run python kometa.py --validate --validate-schema --schema-path /some/path/to/json-schema

docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --validate --validate-schema --schema-path /some/path/to/json-schema
Validate File · -vf/--validate-files · KOMETA_VALIDATE_FILE

Validate a single YAML file against its auto-detected JSON schema and print a gap report. The schema is inferred from the file's root keys: collections: → collection schema, overlays: → overlay schema, playlists: → playlist schema, metadata: → metadata schema, libraries:/plex:/tmdb: → config schema.

Exits with code 0 if no errors, 1 if any errors. Use --schema-path to override the schema directory.

Accepted Values: Path to a YAML file

Shell Flags: -vf, --validate-files, or --validate-file (ex. --validate-file /path/to/collections.yml)

Environment Variable: KOMETA_VALIDATE_FILE (ex. KOMETA_VALIDATE_FILE=/path/to/collections.yml)

Example

uv run python kometa.py --validate-file /path/to/collections.yml

docker run -it -v "X:\Media\Kometa\config:/config:rw" -v "/path/to/files:/files:ro" kometateam/kometa --validate-file /files/collections.yml
Validate Directory · -vd/--validate-directory · KOMETA_VALIDATE_DIR

Walk a directory recursively, validate every .yml and .yaml file found against its auto-detected JSON schema, and print a combined report. Files with an unrecognised structure are skipped with a warning (not an error). Clean files are silent; only files with errors are reported individually.

After all files, a single aggregate gap report is printed showing keys present in your files but missing from the schemas, ranked by how many files contain each key. This is the primary tool for improving the json-schema/ files.

Exits with code 0 if no file had errors, 1 if any file had errors. Use --schema-path to override the schema directory.

Accepted Values: Path to a directory

Shell Flags: -vd, --validate-directory, or --validate-dir (ex. --validate-dir /path/to/configs)

Environment Variable: KOMETA_VALIDATE_DIR (ex. KOMETA_VALIDATE_DIR=/path/to/configs)

Example

uv run python kometa.py --validate-dir /path/to/community-configs

docker run -it -v "X:\Media\Kometa\config:/config:rw" -v "/path/to/configs:/data:ro" kometateam/kometa --validate-dir /data