Jellyfin IMDb Ratings Plugin

Jellyfin.Plugin.ImdbRatings is a custom metadata plugin for Jellyfin that automatically fetches and updates community ratings for your media using the Internet Movie Database (IMDb).

While the source code is open source, the data source for this is the "IMDb Non-Commercial Datasets" which is free to use for personal and non-commercial projects:

Link: https://developer.imdb.com/non-commercial-datasets/

Important

Version 4.0.0 Update - Drastically Reduced Memory Footprint: To make the plugin much friendlier for servers with limited resources, we've transitioned from an in-memory cache to an embedded SQLite database. The plugin now uses virtually no permanent memory while sitting idle.

Features

• IMDb Community Ratings: Automatically retrieves ratings for Movies, Series, and Episodes.
• Calculated Season Ratings: Calculates the average IMDb rating for whole seasons based on their episodes (as IMDb only provides episode-level ratings). Enabled directly via your library options under Season metadata downloaders.
• Official Data Source: Downloads and caches the official IMDb ratings dataset (title.ratings.tsv.gz) directly from IMDb to provide fast, local lookups without web scraping or API rate limits.
• Provider Integration: Acts as a seamless Remote Metadata Provider ("The Internet Movie Database Ratings") that integrates gracefully into Jellyfin's existing metadata refresh pipeline.
• Automatic Background Updates: Includes a built-in scheduler task to keep your library's ratings up-to-date as IMDb scores change over time (defaults to every day at 3 AM).
• Plugin Configuration & Status Dashboard: View live database statistics (number of indexed ratings, file size, dataset download timestamp), and customize cache expiration, minimum episode rating threshold (%), and mirror dataset URLs.

How It Works

The plugin matches your media's existing IMDb ID against the cached IMDb ratings database. If a match is found, the plugin applies the current IMDb community rating to your media item.

To ensure optimal performance, the plugin caches the IMDb ratings flat file in a local SQLite database and only refreshes it from the internet once the configured cache interval (default: 24 hours) has elapsed.

How To Use

1. Navigate to Dashboard -> Libraries in Jellyfin.
2. Click on your Movie or TV Show library.
3. Under the metadata downloaders section, enable The Internet Movie Database Ratings for the item types you want:
   • Movie metadata downloaders
   • Series metadata downloaders
   • Season metadata downloaders (calculates season ratings from episode ratings)
   • Episode metadata downloaders
4. Important (Order Dependency): Ensure The Internet Movie Database Ratings is placed last at the bottom of the list for each item type (below primary fetchers like TheMovieDb, TheTVDB, or OMDb). This ensures the primary fetcher retrieves and saves the IMDb ID (tt...) first, so this plugin can immediately look up and apply the rating during the same scan.
5. Save your settings and re-scan your library or refresh metadata.

Plugin Configuration Page

Navigate to Dashboard -> Plugins -> IMDb Ratings to view the status dashboard and customize settings:

• Live Status: Displays whether the database is ready or updating, the number of ratings indexed, the database size on disk, and the dataset download timestamp.
• Cache Refresh Interval (Hours): How often to check for a newer dataset from IMDb (default: 24 hours).
• Minimum Episode Rating Threshold for Seasons (%): The minimum percentage (0–100%) of rated episodes required in a season before calculating and assigning an average rating to the season (default: 0%).
• Custom Dataset URL: Use a custom mirror or proxy if needed (default: https://datasets.imdbws.com/title.ratings.tsv.gz).

Important Notes & Prerequisites

• Requires IMDb IDs (via NFO or other Providers): To avoid rate limits, this plugin does not perform title-based web searches on IMDb. It requires an IMDb ID (e.g., tt0111161) to look up the rating. It is not mandatory to have these IDs already inserted into your database via local .nfo files, provided you have other metadata fetchers (like TheMovieDb, OMDb, or TheTVDB) enabled for your library to fetch them during the scan.
• Order Dependent: Because this plugin relies on an IMDb ID, make sure to order this plugin below your primary metadata fetchers (like TheMovieDb or OMDb) in your library settings. This ensures the primary fetcher retrieves the ID first, allowing this plugin to successfully apply the rating. (Note: If the plugin is placed in the wrong order, it will not break anything; it simply means the ratings will only be applied during the next metadata refresh or scheduled task run, once the IMDb ID has been fetched and saved by the other provider).
• Jellyfin Compatibility: This plugin is built using .NET 9.0 and requires Jellyfin Server 10.11.x or newer.

Scheduled Task: "Update IMDb Ratings"

To ensure your media ratings don't become stale, this plugin registers a custom Scheduled Task within Jellyfin.

• What it does: The task scans your library for all Movies, Series, Episodes, and Seasons that have the provider enabled in their library options. It updates ratings for movies, series, and episodes using the cached database, and calculates season averages from episodes.
• Default Schedule: By default, the task is configured to run automatically every day at 3:00 AM.
• Manual Execution: You can manually trigger this task at any time or change its schedule by navigating to Dashboard -> Scheduled Tasks -> Library -> Update IMDb Ratings in your Jellyfin server interface.

Troubleshooting

IMDb ratings are missing for Episodes after upgrading to Jellyfin 10.11+ Jellyfin 10.11 heavily refactored its database and metadata parsers. Sometimes, upgrading from 10.10 leaves episode metadata in an incomplete state, or the primary TMDb scraper fails to pull the external IMDb ID for episodes. If your ratings are not appearing for episodes:

1. Ensure you have a fallback metadata provider like OMDb or TheTVDB installed and enabled under your library's Episode Metadata Fetchers.
2. Go to the affected TV Show, click the three dots (...), and select Refresh Metadata.
3. Choose Replace all metadata. This forces Jellyfin to rebuild the underlying database links and pull the missing IMDb IDs so this plugin can read them.

Installation

Method 1: Using the Jellyfin Plugin Repository (Recommended)

1. In your Jellyfin server, navigate to Dashboard -> Plugins -> Repositories.
2. Click the + icon to add a new repository.
3. Enter a name (e.g., "IMDb Ratings") and the following URL: https://raw.githubusercontent.com/verybadsoldier/jellyfin-plugin-imdbratings/refs/heads/repository/manifest.json
4. Go to the Catalog tab, find "IMDb Ratings", and click Install.
5. Restart your Jellyfin server.

Method 2: Manual ZIP Installation

1. Download the latest release .zip file from the repository releases page.
2. Extract the .zip file into your Jellyfin server's plugins directory (e.g., plugins/IMDbRatings).
3. Restart your Jellyfin server.

Post-Installation Steps:

• Navigate to Dashboard -> Plugins to verify the plugin is installed.
• Go to Dashboard -> Scheduled Tasks to adjust the execution triggers for the "Update IMDb Ratings" task if desired.

License

This plugin is licensed under the GNU General Public License v3.0. See the LICENSE file for more details.