Overview

Maintainerr is a self-hosted library maintenance tool for Plex, Jellyfin and Emby. Libraries fill up with films users requested and watched once, half-finished series and titles nobody has touched in years, and the decision about what to delete usually falls on the person running the server. Maintainerr makes that decision from rules: you describe what counts as dead weight (unwatched, unrequested, stale), it gathers the matching titles into a collection, holds them for a grace period so everyone can catch up, and then removes them from the media server, from the *arrs and from Seerr or Ombi. It is written in TypeScript, ships as a Docker image for amd64 and arm64, and has been developed in the open since 2021 under the MIT licence.

Everything runs from a web interface: a sidebar with Overview, Rules, Collections, Calendar, Storage, Overlays and Settings, with rule building, collection management and the automated run schedule handled inside the app.

Key Features

• Rule building across the whole stack: conditions are read from Plex, Jellyfin, Emby, Radarr, Sonarr, Sportarr, Seerr, Ombi, Tautulli, Streamystats and Tracearr, and combined with AND/OR logic so a rule can mean “unwatched for a year and never requested” rather than a single filter.
• Grace period and a Leaving Soon shelf: matched items are collected and held for a configurable period before anything is acted on, and the collection can be pinned to the Plex home screen so users see what is about to go.
• Smart metadata matching: every item is resolved across the media server, the *arrs, Seerr and Ombi by IMDB, TMDB or TVDB id, missing ids are bridged, and each match is sanity-checked by release year so the right title is acted on. A TVDB key can be added as a second metadata source next to the built-in TMDB.
• Actions, not just reports: on handling, Maintainerr can delete files from disk, unmonitor or delete the item in Radarr, Sonarr or Sportarr, change its quality profile, clear the original request in Seerr or Ombi, and clean it out of the download client.
• Plex, Jellyfin or Emby: any of the three can be the media server, rules can be migrated when switching between them, and separate Maintainerr instances can run against separate servers with isolated rules, collections and data.
• Manual and automatic collections: collections can run on rules or be managed by hand, with individual items added or excluded even when they match a rule, and membership changes made inside the media server are synced back.
• Poster overlays: configurable overlays (text, countdown, shapes, images) are rendered onto posters and title cards, and a custom collection poster survives collection recreation.
• Notifications: Discord, Slack, Telegram, Pushover, Gotify, ntfy, Pushbullet, LunaSea, email and generic webhooks, including a warning when a newer Maintainerr release is available.
• Rule sharing: rules export and import as YAML, a community rule library is built in, and rules can be moved between servers.
• Operations extras: cron-scheduled rule and collection runs with live progress, storage metrics, a calendar, logs, health endpoints, an interactive Swagger/OpenAPI API at /api/swagger, and hosting under a subfolder with BASE_PATH.

Why Use Maintainerr

A media server only stays useful while there is space left on the disk and nobody is wading through a wall of unwatched titles to find something to watch. Doing the pruning by hand means both remembering to do it and defending every deletion afterwards. Maintainerr turns the policy into rules, publishes the outcome before it happens through the collection and the Leaving Soon shelf, and then applies the same decision consistently to the media server, the download client and the request tool. Because it reads and writes the rest of the stack rather than replacing it, an existing Plex, Jellyfin or Emby setup plus Radarr, Sonarr, Seerr or Ombi keeps working exactly as it does now.

Typical Uses

• Clearing films that were requested once, watched once and never played again.
• Showing users a Leaving Soon shelf before automated deletion, so anything worth keeping gets watched in time.
• Freeing space on a full disk by targeting the oldest, least-played content instead of deleting at random.
• Dropping whole series that have had no recent activity, while keeping the ones being watched.
• Automating unmonitoring and request cleanup so Radarr, Sonarr, Seerr and the download client stay in step with what is actually on disk.
• Running separate instances for a family Plex server and a test Jellyfin server, each with its own rules.

Getting Started

Maintainerr is deployed as a container: ghcr.io/maintainerr/maintainerr:latest (also published on Docker Hub) for amd64 and arm64, with Compose, Podman Quadlet and Kubernetes examples in the README. State lives in a single directory mounted at /opt/data, and the web interface listens on port 6246. On x86-64 the overlay and collection-poster features use sharp, whose prebuilt binaries need the x86-64-v2 microarchitecture: the app still starts without it, but those features are disabled, so a VM should expose a host or x86-64-v2 CPU type. After the first start you create the admin account, connect the media server and the *arrs, and the installation guide at docs.maintainerr.info walks through the rest.