PlexGaps

PlexGaps scans your Plex library and shows two lists:

• Missing episodes for every series, grouped by season.
• Missing movies from every franchise, for example the rest of a trilogy.

It runs as one Docker container with a small web UI. Results are cached and the library is rescanned on a schedule. Everything is configured from the web UI.

Contents

• How it works
• Install on Unraid
• First-time setup
• Using the web UI
• Settings reference
• Running without Unraid
• Troubleshooting
• Limitations
• Development

How it works

1. PlexGaps reads your TV and movie libraries from Plex and the TMDB, TVDB or IMDb ids Plex stores for each item.
2. TV: for each series it asks TMDB for the full episode list of every season and compares it with the episodes Plex has. Specials and unaired episodes are skipped unless you turn them on.
3. Movies: for each movie it asks TMDB which collection (franchise) the movie belongs to, then lists the other films in that collection that you do not own. Unreleased films are skipped unless you turn them on.
4. Results are saved to /config/results.json and shown in the UI.

PlexGaps only reads from Plex. It never changes your library.

Install on Unraid

From the template repository

1. In Unraid open the Docker tab settings and add this line to Template repositories:

   https://github.com/RayMunro/HackerHog
   

2. On the Docker tab choose Add Container, select PlexGaps from the template list and click Apply.

3. Open the WebUI from the container's menu, or go to http://YOUR-SERVER-IP:8686.

Building the image yourself

docker build -t plexgaps .
docker run -d --name plexgaps --restart unless-stopped \
  -p 8686:8686 -v /mnt/user/appdata/plexgaps:/config plexgaps

If you build under a different image name, change the Repository field in the container settings to match.

First-time setup

You need two things:

• Plex token. In Plex Web open any item, choose Get Info, then View XML. The token is the X-Plex-Token= value in the address bar.
• TMDB API key. Create a free account at themoviedb.org, then open Settings, API. Either the "API Key" or the long "API Read Access Token" works.

Then:

1. Open the web UI. With nothing configured it opens on the Settings tab.
2. Enter the Plex URL (for example http://192.168.1.10:32400), the Plex token and the TMDB key.
3. Click Test connection. Plex and TMDB are checked separately and your libraries appear as checkboxes.
4. Untick any library you do not want scanned. Leaving all ticked scans every library.
5. Click Save and scan.

Secrets are stored in /config/settings.json (readable only by the container user) and are never sent back to the browser. Leave a secret field blank to keep the saved value.

Using the web UI

Items that could not be matched on TMDB are listed at the bottom of each tab. Fixing the match in Plex (Fix Match) and rescanning clears them.

Settings reference

All options can be set on the Settings tab. Environment variables are optional and only provide the starting values. Anything saved in the UI takes priority.

The container exposes port 8686 and stores its data in /config.

Running without Unraid

Any Docker host works:

docker run -d --name plexgaps --restart unless-stopped \
  -p 8686:8686 -v plexgaps-config:/config ghcr.io/raymunro/plexgaps:latest

Troubleshooting

View the container log for details:

docker logs plexgaps

Limitations

• Episode numbering follows TMDB.
• Franchises come from TMDB collections only.
• Only libraries of type TV and Movie are scanned.

Development

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt pytest
.venv/bin/python -m pytest
DATA_DIR=./data .venv/bin/uvicorn app.main:app --port 8686

Layout:

Pushing to main runs the tests and publishes ghcr.io/raymunro/plexgaps:latest for amd64 and arm64. Pushing a tag such as v1.0.0 also publishes versioned tags. After the first publish, set the package visibility to Public in the GitHub package settings so Unraid can pull it.

The Unraid template lives in the HackerHog repository (templates/plexgaps.xml), and the project is licensed GPL-3.0-or-later.