Rating update tool for IMDB ratings in Plex libraries

A tool to update the IMDB ratings for Plex libraries that contain movies via the IMDB, TMDB and TVDB agents.

<span class="badge-paypal"><a href="https://paypal.me/mynttt" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate button" /></a></span>

Important

[!CAUTION] While recent database issues have been resolved and the tool has proven stable for most users, it should still be used with caution.

Plex uses SQLite, which is not fully ACID-compliant and can become unstable when accessed concurrently by multiple processes.

While most users experience no issues, this setup can theoretically lead to database corruption — especially when the Plex database is stored on NFS shares.

Make sure you take backups of your database when initially testing out this tool on your setup!

Running this tool on a desktop PC or in a shared Docker volume is considered safe.

However, functionality may break if the Plex database schema changes or if IMDb stops providing a public rating dataset. In such cases, the tool will safely stop execution without affecting your database.

The author assumes no responsibility for any potential damage to your Plex Media Server database.

Plex Official DB Repair Instructions - DBRepair Community Tool

[!NOTE] If you receive rating updates for episodes but not for TV shows, you need a TVDB API key.

This occurs because the tool retrieves IMDb IDs for episodes directly from the database, but for TV shows it only finds TVDB IDs. These must be resolved into IMDb IDs via the TVDB API, which requires a valid key.

Without an API key, TV show ratings cannot be updated - you can get a free TVDB API key through their points system.

[!TIP] The new Plex TV Show agent is now the default for Plex libraries.

This tool supports the new agent, but fallback support is limited — it currently only works with TVDB v4 and not TMDB v3.

To enable processing of libraries that use the new agent, you must explicitly opt in. Otherwise, those libraries will be skipped.

Read more about how to opt in here.

---

• to run this without docker on Linux in a headless mode check out this issue
• if you want to run this on Windows without docker look here - there is also a GUI for the tool that is discussed here.

What does this do?

The Plex IMDB agent is kind of meh... Sometimes it is not able to retrieve the ratings for newly released movies even tho it matches the IMDB ID with them. It is impossible to comfortable add the rating manually from the users perspective.

This tool allows you to update the database that stores this data with the correct IMDB ratings. It will correct outdated and missing ratings and also set a flag to display the IMDB badge next to the ratings. The source used to retrieve the ratings is the official IMDB dataset that is updated daily and free for non-commercial use. Its download and refreshment will be handled automatically by this tool.

An advantage is that it works outside Plex by manipulating the local Plex database. Thus, no metadata refresh operations have to be done within Plex. It is faster and will not lead into the unforeseen consequences that one sometimes experiences with a Plex metadata refresh (missing or changed posters if not using a custom poster).

Before (Not IMDB matched) | After Match :-------------------------:|:-------------------------: |

Above are two different movies, that why the genres changed

This tool processes the following libraries:

Type | Description | Agent :-------------------------:|:-------------------------:|:-------------------------: MOVIE | Plex Movie Agent with IMDB | com.plexapp.agents.imdb MOVIE | TMDB Movie Agent (if TMDB API key set) | com.plexapp.agents.themoviedb MOVIE | New Plex Movie Agent (if IMDB as ratings source set) | tv.plex.agents.movie TV SHOW | New Plex TV Show Agent (currently only for items that have the IMDB ID embedded in the Plex database and have been opted-in via a special environment variable) | tv.plex.agents.series TV SHOW | TMDB Series Agent (if TMDB API key set) | com.plexapp.agents.themoviedb TV SHOW | TVDB Series Agent (if TVDB auth string set) |com.plexapp.agents.thetvdb

In my library with 1800 movies it transformed entries for 698 items and 1000+ entries for series. If it is left running, every few days when a new IMDB data set is pulled a few ratings will update as well.

Docker

Docker is on dockerhub | UnRaid instructions

Environment Variables Guide

Name | Description :-------------------------:|:-------------------------:| RESTART_ON_CRASH|Automatically restarts the tool within the docker in case a crash is encountered. This must be set to true to have any effect. Once a crash is encountered, the docker container will not stop anymore but instead wait 10 seconds before trying to launch the tool again. USE_PLEX_SQLITE_BINARY_FOR_WRITE_ACCESS|Allows to use the non-standard Plex SQLite3 version that diverged so strongly from the vanilla flavour that write operations with vanilla SQLite3 can cause database corruptions! Set this to true in the docker when using a version >= 1.6.0! This is the only way to be safe from corruptions as Plex continues to diverge from compatibility with vanilla SQLite3! If you're not using a docker version make sure that this points to the Plex Media Server/Plex SQLite binary that is located in the main Plex folder next to the Plex Media Server executable. OVERRIDE_DATABASE_LOCATION|Overrides the path where UpdateTool looks for the Plex database. The database needs to be contained in this folder. Useful if a docker container uses a volume and a different path structure. (more here) TMDB_API_KEY|Enables TMDB Movie/Series library processing TVDB_API_KEY|Enables TVDB Series library processing using either the v3 legacy key or the v4 pin UNLOCK_FOR_NEW_TV_AGENT|Opt-in for libraries using the new TV Show agent. All libraries that are opted-in this way will have their ratings changed to IMDB ratings by this tool (more here) IGNORE_LIBS|Ignore libraries with certain IDs (more here) CAPABILITIES|Custom flags for the tool (more here) JVM_MAX_HEAP|Only relevant for the docker. Specify max. heap allocatable by the JVM (default 256m). Can be useful if you have a really large library (40000+ items) and you run in memory related crashes. Must be specified in bytes (i.e. 256m, 1g, 2g, 512m)

Deprecated variables can still be used although their usage is discouraged.

Deprecated Environment Variables

Name | Description | Deprecation :-------------------------:|:-------------------------:|:-------------------------:| TVDB_AUTH_STRING|Enables TVDB Series library processing|API Key is enough for this tool to work

Docker on UnRaid

~~There is a template repository available now: https://github.com/mynttt/unraid-templates~~ - No support for UnRaid atm - make sure to just run the docker image there.

After completing the configuration steps, you can start the container. If it has errors, it will stop. The log in the config folder shows you what it does or why it crashed if that happens.

TMDB and TVDB are optional settings that are not required for base movie imdb operations! TMDB unlocks matching for movies that have a TMBD match for whatever reason, TMDB matched series libraries and TVDB allows to update series as well!

To run your docker without UnRaid templates:

docker pull mynttt/updatetool

# Without TMDB fallback

docker run -dit -e RUN_EVERY_N_HOURS=12 \
    -v "/mnt/data/Plex Media Server":/plexdata \
    -v "/mnt/data/imdpupdaterconfig":/config \
    mynttt/updatetool

# With TMDB fallback

docker run -dit -e RUN_EVERY_N_HOURS=12 \
    -e TMDB_API_KEY=yourkey \
    -v "/mnt/data/Plex Media Server":/plexdata \
    -v "/mnt/data/imdpupdaterconfig":/config \
    mynttt/updatetool
    
# With TMDB fallback and TVDB resolvement for series

docker run -dit -e RUN_EVERY_N_HOURS=12 \
    -e TMDB_API_KEY=yourkey \
    -e TVDB_API_KEY=tvdbapikey \
    -v "/mnt/data/Plex Media Server":/plexdata \
    -v "/mnt/data/imdpupdaterconfig":/config \
    mynttt/updatetool

Explained:

docker run -dit 
     # Invoke every 12h
    -e RUN_EVERY_N_HOURS=12 \
     # Optional parameter: will try to get an IMDB ID from TMDB matched items
    -e TMDB_API_KEY=yourkey \
    -e TVDB_API_KEY=tvdbapikey \
     # The plex data root (that contains Plug-ins, Metadata, ...
     # https://support.plex.tv/articles/202915258-where-is-the-plex-media-server-data-directory-located/
    -v "/mnt/data/Plex Media Server":/plexdata \
     # A path where you want to store the log and state files
    -v "/mnt/data/imdpupdaterconfig":/config \
    mynttt/updatetool

[Where is