Plex-Trakt-Sync

This project adds a two-way-sync between trakt.tv and Plex Media Server. It requires a trakt.tv account but no Plex premium and no Trakt VIP subscriptions, unlike the Plex app provided by Trakt.

Originally created by @Taxel, now maintained by contributors.

Note: The PyTrakt API keys are not stored securely, so if you do not want to have a file containing those on your harddrive, you can not use this project.

Contribute

Looking for a way to contribute?

• find issues with the help-wanted label
• improve documentation docs-needed label
• you can also just create a pull request to improve documentation
• ... more developer contribution docs

---

• Plex-Trakt-Sync
  • Features
  • Pre-requisites
  • Installation
    • pipx
    • Docker Compose
    • Install code from Pull request, development
    • Windows Setup (optional alternative), unsupported
    • Unraid setup, unsupported
    • GitHub, unsupported
  • Setup
  • Configuration
    • Libraries
    • Per server configuration
    • Logging
  • Commands
    • Sync
    • Unmatched
    • Info command
    • Inspect
    • Watch
      • Systemd setup
      • Systemd user setup
  • Good practices
  • Troubleshooting

Features

• Media in Plex are added to Trakt collection
• Ratings are synced
• Watched status are synced (dates are not reported from Trakt to Plex)
• Liked lists in Trakt are downloaded and all movies in Plex belonging to that list are added
• Watchlists are synced
• You can edit the config file to choose what to sync
• None of the above requires a Plex Pass or Trakt VIP membership. Downside: Needs to be executed manually or via cronjob, can not use live data via webhooks.

Pre-requisites

The script is known to work with Python 3.10-3.13 versions.

Installation

pipx

Installation with pipx.

pipx install PlexTraktSync

or, to install specific version:

pipx install PlexTraktSync==0.15.2 --force

and to upgrade:

plextraktsync self-update

which just calls pipx with:

pipx upgrade PlexTraktSync

to run:

plextraktsync sync

NOTE: pipx install will use OS specific paths for Config, Logs, Cache, see platformdirs documentation for details or check output of info command.

Docker Compose

You can setup docker compose file like this:

version: "2"
services:
  plextraktsync:
    image: ghcr.io/taxel/plextraktsync
    command: sync
    container_name: plextraktsync
    restart: on-failure:2
    volumes:
      - ./config:/app/config
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Tallinn

You can use specific version 0.25.16:

• image: ghcr.io/taxel/plextraktsync:0.25.16

or latest 0.25.x version:

• image: ghcr.io/taxel/plextraktsync:0.25

Note: main is development version and reporting bugs against development versions are not supported.

Run the Docker Container

To run sync:

docker compose run --rm plextraktsync sync

The container will stop after the sync is completed. Read Setup section to run it automatically at set intervals.

Install code from Pull request

This is to install development version to test if pull request would fix some problem.

See contributing guide how to install code from pull request.

Windows Setup (optional alternative)

NOTE: This installation method is not supported. It's documented solely by user contribution.

• Download the latest .zip release from https://github.com/Taxel/PlexTraktSync/tags
• Run setup.bat to install requirements and create optional shortcuts and routines (requires Windows 7sp1 - 11).

Unraid setup

NOTE: This installation method is not supported. It's documented solely by user contribution.

Option 1 for container creation: Create a manual Unraid container of PlexTraktSync:

• Go to the Docker section, under "Docker Containers" and click "Add Container".
  • Click the advanced view to see all of the available parameters.
  • Leave the template blank/unselected.
  • Under Name: enter a name for the docker (e.g., PlexTraktSync).
  • Under Repository: enter ghcr.io/taxel/plextraktsync:latest (or whatever tag you want).
  • Under Extra Parameters: enter -it for interactive mode.
• Click "Apply".
• The container should start automatically. If not, start it.
• Enter the console for the container.
• Enter plextraktsync to start the credential process described above.

Option 2 for container creation: Utilize the "Community Apps" Unraid Plugin.

• Go to the Plugins tab, paste the Community Apps URL in the URL area, and click "Install".

Once installed (or if already installed):

• Go to the (newly created) Apps tab and search "plextraktsync", and click on the App, and click "Install" (https://forums.unraid.net/topic/38582-plug-in-community-applications/)
• Take all the default settings (the -it switch as outlined elsewhere in the README is already present), and click "Apply".
• The container then installs, and will start.

Schedule (cron) the container to start at given intervals to process the sync

• Go to the Plugins tab, past the User Scripts URL in the URL area, and click "Install" (https://forums.unraid.net/topic/48286-plugin-ca-user-scripts/)

Once installed (or if already installed):

• Go to the Plugins tab, click on "User Scripts", and click the "Add New Script" button
• Name your script accordingly
• Click the "gear" icon next to the script name, and click "Edit Script"
• Remove the "#!/bin/bash" line and add:

#!/bin/bash

# Check if the container is running
if [ "$(docker ps -q -f name=PlexTraktSync)" ]; then
    echo "PlexTraktSync container is already running."
    exit 1
else
    echo "PlexTraktSync container is not running. Starting it now..."
    docker start PlexTraktSync
fi

# Run the sync command inside the container
docker exec PlexTraktSync plextraktsync sync

• The format of the script needs to be docker calling your container name (if you changed it from the default, ie to something like plex-trakt-sync), then issuing the command to sync.
• Click "Save Changes"
• Set the schedule accordingly using the dropdown menu next to the "Run in Background" button

GitHub

NOTE: This installation method is not supported. You will not get support if you use this installation method.

Installing from GitHub is considered developer mode, and it's documented in CONTRIBUTING.md.

Setup

• You will need to create a Trakt API app if you do not already have one:

  • Visit https://trakt.tv/oauth/applications/new
  • Give it a meaningful name
  • Enter urn:ietf:wg:oauth:2.0:oob as the redirect url
  • You can leave Javascript origins and the Permissions checkboxes blank

• Run plextraktsync login, the script will ask for missing credentials

  Note To setup the credentials in the Docker Container, refer to the Run the Docker Container section

  Note2 If you are not able to run a docker container from commandline, like on a Synology NAS, run an instance of plextraktsync on a different device to create the necesary .env, .pytrakt.json and servers.yml files. Move them to the mapped /app/config folder and rebuild the container.

• At first run you will be asked to setup Trakt and Plex access.

  Follow the instructions, your credentials and API keys will be stored in .envand .pytrakt.json files. Plex URL and token is stored in servers.yml.

  If you have 2 Factor Authentication enabled on Plex, input the code when prompted. If you don't have 2FA enabled, just leave the prompt blank and press Enter.

• Cronjobs can be optionally used on Linux or macOS to run the script at set intervals.

  For example, to run this script in a cronjob every two hours:

  $ crontab -e
  0 */2 * * * $HOME/.local/bin/plextraktsync sync
  

  • Note the command in the example above may not immediately work. Use the which plextraktsync command to locate your system's plextraktsync executable file and update it accordingly.

• Instead of cron, a docker scheduler like Ofelia can also be used to run the script at set intervals.

A docker compose example with a 6h interval:

version: "2"
services:
  scheduler:
    image: mcuadros/ofelia: