Plex Librarian

Find unwatched media, manage users, save bandwidth and space.

Install · Features · Integrations · Configuration · Get help

Stale analysis · Duplicates · Episode & Season Gaps · Activity

Plex Librarian helps you keep your Plex library under control: find media nobody watches, remove redundant copies, and review user activity. Built for Docker and Unraid, with optional Sonarr, Radarr, Seerr, and qBittorrent connections.

What it does

Installation

Unraid

Open Plex Librarian in Community Apps, or search for Plex Librarian in the Apps tab. Keep the defaults, select Apply, then open the web UI from the Docker page.

Choose Sign in with Plex, select your server, and let the first sync finish.

Docker Compose

Save this as compose.yml:

services:
  plex-librarian:
    image: edon231/plex-librarian:latest
    container_name: plex-librarian
    ports:
      - "8288:8080"
    volumes:
      - plex-librarian-data:/data
    restart: unless-stopped

volumes:
  plex-librarian-data:

Start it:

docker compose up -d

Open http://<docker-host>:8288, choose Sign in with Plex, and select your server.

Images support AMD64 and ARM64 and are available on Docker Hub and GHCR (ghcr.io/brycepearce/plex-librarian). Use latest for stable releases, a version tag to pin a release, or edge for builds from main.

Keep /data persistent; it holds the database and settings. You can replace the named volume with a bind mount such as /path/to/appdata:/data. Ordinary cleanup uses service APIs and needs no media mounts or Docker socket.

Integrations

Open Settings → Media connections to add your services. Multiple instances are supported.

• Sonarr / Radarr: add the service URL and API key, then assign Plex libraries. Include the manager in a cleanup to coordinate removal.
• Seerr: add the service URL and API key to enable request follow-through on the Users page.
• qBittorrent: add the Web UI URL and credentials to optionally remove verified downloads during cleanup.

Use addresses reachable from inside the Librarian container, such as http://192.168.1.20:8989 or http://sonarr:8989 on a shared Docker network. localhost points to Librarian's own container.

Sonarr/Radarr and qBittorrent cleanup start unchecked. Review the preview and choose which services should delete content before confirming. Track results and any steps needing attention on the Activity page.

Upgrading from the retired host-discovery helper? Follow the upgrade guide to retire the separate helper.

Sonarr/Radarr download source cleanup

Librarian uses Sonarr/Radarr import history to find the original downloaded files associated with the media being removed, including copies or hardlinks still in the download folder. It verifies ownership and file identity before cleanup. To enable this optional cleanup, mount the same host download folder that Sonarr/Radarr uses into Plex Librarian with read/write access. This is optional; ordinary service API cleanup does not need this mount. Keep the existing /data app-data mount unchanged.

Unraid: open Docker → Plex Librarian → Edit, set Completed downloads folder to your host folder (for example, /mnt/user/downloads/complete), use /cleanup-downloads as the container path with Read/Write access, and Apply.

Docker Compose: add this entry under Librarian's existing volumes: list, replacing source with your host's completed-downloads folder:

- type: bind
  source: /mnt/user/downloads/complete
  target: /cleanup-downloads
  read_only: false
  bind:
    create_host_path: false

Run docker compose up -d again. Then open Settings → Media connections → Download cleanup, finish setup, and enable cleanup after the access check. For manual setup, enter the download folder as Sonarr/Radarr sees it and /cleanup-downloads as the folder in Librarian. The container paths can differ, but must refer to the same host files. Choose the completed-downloads folder, rather than an individual movie or season folder.

Configuration

Most settings live in the web UI: daily sync scheduling with your time zone, stale-media thresholds, user insights, and ignored titles. Add titles to Settings → Ignored content to exclude them from insights and cleanup tools.

http://<plex-librarian-host>:8288/api/webhook/plex

Backups and access

Back up /data; it contains the database and service credentials.

Deploy on a trusted network. For remote access, use a reverse proxy with authentication and TLS. Plex sign-in connects your server; it does not restrict access to Librarian's web UI or API.

Support and contributing

Report a bug or suggest a feature. For development, use Deno 2.9.7 and run deno task fmt and deno task verify before submitting changes.

AI-assisted contributions are reviewed, tested, and maintained by the project. Licensed under the MIT License.