Installing Kometa

Generally, Kometa can be installed in one of two ways:

1. Running on a system as a Python script [we will refer to this as a "local" install]
2. Running as a Docker container

GENERALLY SPEAKING, running as a Docker container is simpler, as you won't have to be concerned about installing Python, or support libraries, or any possible system conflicts generated by those actions.

For this reason, it's generally recommended that you install via Docker rather than directly on the host.

If you have some specific reason to avoid Docker, or you prefer running it as a Python script for some particular reason, then this general recommendation is not aimed at you. It's aimed at someone who doesn't have an existing compelling reason to choose one over the other.

There is no UI

Kometa is an inherently technical tool, and as such, it does not have a graphical user interface. It is run from the command line, and all configuration is done via a config.ymlfile. Kometa will create a template config when it starts up if one is not found, but you will need to edit it to make it useful. The Configuration page describes this file.

Where to install Kometa

Kometa communicates with all services [Plex, Radarr, Trakt, etc] via their network APIs, so Kometa does not have to be installed on the same machine as Plex. Kometa does not require [nor would it use] access to the file system behind your Plex libraries.

Perhaps your Plex server is remote and you want to run Kometa on a machine in your home. That's fine. The relative locations of Kometa and Plex have no effect on the installation[except perhaps the URL you would use in the config].

Install Walkthroughs

The installation overviews on this page are aimed at users who have previous experience of installing services via command-line terminal commands.

For those who need full installation walkthroughs, please refer to the following walkthrough guides:

• Local Walkthrough - follow this if you are running the script directly on Windows, OS X, or Linux
• Docker Walkthrough - this discusses using Docker at the command line

If you are using unRAID, Kubernetes, QNAP, or Synology refer to the following basic guide to Docker container setup for each system:

this doesn't cover the Kometa setup specifics found in the guides above with regard to creating the config file and Collection File, so you may want to go through the Docker Walkthrough first on your computer to gain that understanding.

• unRAID Walkthrough
• Kubernetes Walkthrough
• QNAP Walkthrough
• Synology Walkthrough

Local Install Overview

Kometa is compatible with Python 3.9 through 3.13. Kometa has not been tested and may be non-functional on any version of Python beyond 3.13

These are high-level steps which assume the user has knowledge of python and pip, and the general ability to troubleshoot issues. For a detailed step-by-step walkthrough, refer to the Local Walkthrough guide.

1. Clone or download and unzip the repo.

git clone https://github.com/Kometa-Team/Kometa

2. Install dependencies:

pip install -r requirements.txt

3. If the above command fails, run the following command:

pip install -r requirements.txt --ignore-installed

At this point Kometa has been installed, and you can verify installation by running:

python kometa.py

Docker Install Overview

Docker Run:

These are high-level steps which assume the user has knowledge of Docker, and the general ability to troubleshoot issues. They do not cover creating a config.yml file or other configuration details which may be required to get Kometa to do anything substantive. The steps only cover the basics of creating a container. For a detailed step-by-step walkthrough, refer to the Docker Walkthrough guide.

docker run -it -v <PATH_TO_CONFIG>:/config:rw kometateam/kometa

• The -it flag allows you to interact with the script when needed (such as for Trakt or MyAnimeList authentication).
• The -v <PATH_TO_CONFIG>:/config:rw flag mounts the location you choose as a persistent volume to store your files.

• this command will run the container in the foreground, waiting until 5AM to run; if you want it to run right now or run at a different time, or run in the background, you will need to add some flags to the command.

  • Change <PATH_TO_CONFIG> to a folder where your config.yml and other files are [the assumption here is that they already exist].
  • The docker image defaults to running the configuration file named config.yml which resides in your persistent volume.
  • If your directory has spaces (such as "My Documents"), place quotation marks around your directory pathing as shown here: -v "<PATH_TO_CONFIG>:/config:rw"

Example Docker Run commands:

These docs are assuming you have a basic understanding of Docker concepts. One place to get familiar with Docker would be the official tutorial.

Run in the foreground and wait until 5AM to wake up

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

Run in the background and wait until 5AM to wake up

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

Run in the background and wait until 5PM to wake up

docker run -it -d -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --times 17:00

Run immediately in the foreground, then exit when done

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

Run immediately in the foreground, exit when done, delete the container when done

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

Docker Compose:

This is an example docker-compose.yml file that provides a minimal setup for running Kometa. You will need to edit it to suit your environment before use (see the volume mapping).

Any additional customizations, such as setting your local timezone or other Environment Variables can be added manually.

services:
  kometa:
    image: kometateam/kometa
    volumes:
      - /path/to/config:/config
    restart: unless-stopped

Dockerfile

A Dockerfile is included within the GitHub repository for those who require it, although this is only suggested for those with knowledge of dockerfiles. The official Kometa build is available on the Dockerhub Website.

Customizing the docker-compose file with runtime flags and ENV vars

Kometa's behavior can be modified in a variety of ways using either runtime flags or environment variables. These flags and vars are detailed here.

This is optional, and is not necessary to run Kometa. Many if not most users will have no reason to do this and can use something more like the basic docker-compose just above.

This example docker-compose would create a container that runs immediately upon start (rather than waiting until 5AM), uses a particular config file, processes only overlays on only one library, and exits when done. Those four changes are made by the four environment: entries, which are discussed in detail after the example:

As with the one above, this is an example docker-compose which will have to be edited to suit your environment before use.

Press the icon to learn more

services:
  kometa:
    image: kometateam/kometa
    container_name: kometa
    environment:
      - KOMETA_RUN=true #(1)!
      - KOMETA_CONFIG=/config/special-config.yml #(2)!
      - KOMETA_OVERLAYS_ONLY=true #(3)!
      - KOMETA_RUN_LIBRARIES=Movies #(4)!
    volumes:
      - /path/to/config:/config

1. Tells Kometa to run right away
2. Points Kometa at a particular config file
3. Tells Kometa to run overlays only
4. Tells Kometa to process only a library called "Movies"

Again, a list of the available environment variables can be found here.