stevezzau/shortlist repository overview

⁠Shortlist

Shortlist is a free, open-source, self-hosted tool that gives each person on your Plex server their own recommendation rows (Picked for You, Because you watched, seasonal picks, the titles they asked for), built from what they watched and hidden from everyone else. One Docker container, no AI key required.

Stable 1.x, running nightly on a 40-user server. latest is the current stable release.

Website⁠ · Tools compared⁠ · Source on GitHub⁠ · Report a bug⁠

⁠The problem

Everyone on your Plex server sees the same recommendation rows. Plex's Recommended and Home shelves come from the library, not from the person looking at it — so the friend who has watched every sci-fi film you own and the one who only watches comedies get an identical home screen.

Shortlist gives each user their own rows, built from their own watch history, containing only titles that are already in your library and that they haven't seen.

And it's private: each person sees only their own rows, nobody else's.

⁠How the privacy works

Plex has no per-user collections. It does have label restrictions on share filters, which Plex evaluates per account. Each row is labelled shortlist_<user>, and label!=shortlist_<user> is merged into every other account's share filter — leaving one person who can see it.

The ordering is what makes it safe. Every run delivers rows unpromoted, merges the exclusions into every share filter, and only then promotes rows onto Home. A row is never visible before the rule that hides it exists.

This needs Plex Media Server 1.43.2.10687 or newer and a Plex Pass on the admin account. Earlier versions ignored label restrictions on the Home, Recommended and Related shelves, which is why older forum threads say this can't be done.

⁠Quick start

docker run -d --name shortlist \
  -p 5959:5959 \
  -e PUID=1000 -e PGID=1000 -e TZ=Etc/UTC \
  -v /path/to/config:/config \
  stevezzau/shortlist:latest

Then open http://your-host:5959⁠ and follow the setup wizard — it connects your Plex account, picks your server, and walks you to your first rows in about ten minutes.

Try it without touching your server: add -e SHORTLIST_DRY_RUN=1 and Shortlist will show you exactly what it would do and write nothing to Plex.

⁠docker-compose

services:
  shortlist:
    image: stevezzau/shortlist:latest
    container_name: shortlist
    restart: unless-stopped
    ports:
      - "5959:5959"
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Etc/UTC
    volumes:
      - /path/to/config:/config

⁠Tags

Multi-arch: linux/amd64 and linux/arm64.

⁠What you get

• Private rows for every user, built from their watch history. One container serves your whole server, including you, so it's just as useful on a one-person server.
• No AI key required. The built-in picker runs entirely in code. An optional LLM (Claude, GPT, Gemini, or a local model via Ollama, llama.cpp, LM Studio, vLLM or LocalAI) adds one extra source, a live web search for current titles TMDB and Trakt miss.
• No hallucinated picks. Every title is verified to exist in your library before it's delivered.
• Every pick explains itself — "Because you watched Arrival".
• Six row kinds, eleven templates: Picked for You, Because you watched, Watch it again, Popular on this server (shared), Seasonal and Your requests. Add as many rows as you like, each with its own sources, size, libraries, refresh cadence and audience.
• Seasonal rows — a row that follows the calendar: Halloween, Christmas and Valentine's Day, ten ready-made holidays such as Thanksgiving and Easter, or your own dates. Ranked for each person and hidden between seasons.
• Radarr/Sonarr or Overseerr requests (optional) when a strong pick isn't in your library yet, with an approval inbox.
• A "Your requests" row — what each person asked for in Overseerr, or tagged with their name in Radarr/Sonarr, once it's on Plex and until they've watched it. No AI; a person with nothing ready simply has no row.
• Kometa-friendly: never touches a collection it didn't create.
• Provable uninstall: share filters are snapshotted before the first change and restored exactly.

⁠Configuration

Settings live in the app's web interface, not in environment variables. The only environment variables that stay live are infrastructure ones: PUID, PGID, TZ, PORT, APP_BASE_PATH, and SHORTLIST_DRY_RUN.

Full list: Reference⁠.

⁠Requirements

• Plex Media Server 1.43.2.10687 or newer, with a Plex Pass on the admin account
• A free TMDB⁠ API key
• A volume mounted at /config

⁠Links

• Documentation⁠
• Getting started⁠
• How per-user Plex collections work⁠
• Plex recommendation tools compared⁠
• FAQ⁠

MIT licensed. Not affiliated with Plex Inc. Plex is a trademark of Plex, Inc.