plex-librarian

Library health insights for your Plex server — find stale content, track viewing patterns, and reclaim disk space.

Unraid / Docker

Unraid (Community Applications)

Add the template repository URL in Settings → Docker → Template Repositories:

https://raw.githubusercontent.com/BrycePearce/plex-librarian/main/

Then install PlexLibrarian from the Apps tab. Map /data to a persistent path (e.g. /mnt/user/appdata/plex-librarian) and open the web UI to complete setup.

Docker Compose

services:
  plex-librarian:
    image: ghcr.io/BrycePearce/plex-librarian:latest
    container_name: plex-librarian
    ports:
      - "8288:8080"
    volumes:
      - /path/to/appdata:/data
    environment:
      # Optional: skip the OAuth wizard by providing credentials directly
      # PLEX_URL: http://192.168.1.100:32400
      # PLEX_TOKEN: your-plex-token
    restart: unless-stopped

Environment variables

Migrations run automatically on startup. No manual database setup required.

Sync concurrency defaults are deliberately conservative to keep the container's footprint small, especially since Plex itself often runs on the same host. Only raise these if you're running on dedicated hardware with room to spare.

Manual Plex setup (skip OAuth)

Set both PLEX_URL and PLEX_TOKEN to bypass the setup wizard entirely.

Finding your token: In Plex Web, play any item, then click the three-dot menu → "Get Info" → "View XML". Your token is the X-Plex-Token query parameter in the URL. Alternatively, browse to http://<your-plex-host>:32400/identity?X-Plex-Token=<token> — if you get a valid response, the token works.

Finding your server URL: Use http://<local-ip>:32400 for a local server. plex.tv relay URLs (https://xxx.plex.direct:...) also work but local is faster.

Webhooks (Plex Pass only)

Webhooks enable real-time lastViewedAt updates when someone plays or finishes a title, without waiting for a manual sync.

In Plex Web, go to Settings → Webhooks → Add Webhook and enter:

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

If you set PLEX_WEBHOOK_SECRET, append ?token=<secret> to the URL. Requests without a matching token are rejected with 401.

API

Development

Prerequisites: Deno 2.x

# Copy and fill in env vars
cp backend/.env.example backend/.env

# Start backend + frontend dev servers
deno task dev

Backend: http://localhost:8080 · Frontend: http://localhost:5173

Database

Migrations run automatically when the server starts. To generate a new migration after schema changes:

cd backend && deno task db:generate

Other backend tasks (run from backend/):

deno task fmt    # format
deno task lint   # lint