Skip to content

INSTALL.md

Latest commit

 

History

History
159 lines (105 loc) · 6.32 KB

INSTALL.md

File metadata and controls

159 lines (105 loc) · 6.32 KB
Raw

📖 Full Installation Guide — Plex Missing

The detailed, hold-your-hand version, covering Windows, macOS, and Linux, plus a troubleshooting section at the end. For the quick version, see README.md.

Table of contents

Before you start

You'll need Python 3.8+, a Plex server + token, and a free TheTVDB API key. About 10 minutes total. The Sonarr and qBittorrent pieces are optional and can be added anytime.

Step 1 — Get your Plex token

  1. Sign in to Plex in a browser and open any movie or show.
  2. Click ⋯ (More) → Get Info → View XML.
  3. In the URL of the new tab, copy the value after X-Plex-Token=.

Full guide: https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/

You'll also need your server's address, like http://192.168.1.10:32400 (its local IP + Plex's port 32400).

Step 2 — Get a free TheTVDB API key

The TV missing-episode feature checks your shows against TheTVDB, which needs a free key.

  1. Create a free account at https://thetvdb.com.
  2. Go to https://thetvdb.com/dashboard/account/apikey.
  3. Generate a key and copy it.

(You can skip this if you only want the Languages tab, but the TV dashboard won't work without it.)

Install on Windows

  1. Install Python 3 from https://www.python.org/downloads/ — tick "Add python.exe to PATH" during install.
  2. On this project's GitHub page: green Code button → Download ZIP, then unzip it.
  3. Double-click install-windows.bat. It sets everything up and creates your .env file.
  4. Continue to Step 3.

Install on macOS

  1. Check for Python: open Terminal and run python3 --version. If missing, install from https://www.python.org/downloads/.
  2. Download the ZIP (green Code button → Download ZIP) and unzip it.
  3. Double-click install-mac.command.
    • First time, macOS may warn it's from an "unidentified developer." Fix: right-click the file → Open → Open. (Once per file.)
    • If it still won't run, see the chmod tip.
  4. Continue to Step 3.

Install on Linux

python3 --version
sudo apt install python3-venv python3-pip   # Debian/Ubuntu; adjust for your distro

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Then edit .env (Step 3) and run python app.py (Step 4).

Step 3 — Fill in your configuration (.env)

Open the .env file (the installer created it) in any text editor and fill in at least these:

# App login — pick your own:
AUTH_USERNAME=admin
AUTH_PASSWORD=pick_a_strong_password

# Plex (from Step 1):
PLEX_URL=http://192.168.1.10:32400
PLEX_TOKEN=paste_your_plex_token

# TheTVDB (from Step 2):
TVDB_API_KEY=paste_your_tvdb_key

Leave the optional Sonarr/qBittorrent values blank for now if you don't use them. Save the file and make sure it's named exactly .env (not .env.txt — see Troubleshooting).

Step 4 — Run the app and log in

  • Windows: double-click start-windows.bat.
  • Mac: double-click start-mac.command.
  • Linux: source venv/bin/activate then python app.py.

Open http://localhost:5090 in your browser and log in with the username/password you set in .env.

First time in: pick a library from the dropdown and click SCAN. The scan runs in the background with a progress bar; results fill in as it goes. Click any show to see its missing episodes. Use the LANGUAGES button for the audio/subtitle gap scanner.

To use it from another device on your network, replace localhost with the IP of the computer running it, e.g. http://192.168.1.50:5090. Stop the app by closing its window (or Ctrl+C).

Optional integrations

Sonarr

In .env, set SONARR_URL (e.g. http://localhost:8989/api/v3) and SONARR_API_KEY (Sonarr → Settings → General → API Key). The "Sonarr Get" buttons will then trigger searches. The app matches shows to Sonarr by title.

qBittorrent

Enable the Web UI in qBittorrent → Tools → Options → Web UI, note the port, username, and password, and put them in .env as QBIT_URL, QBIT_USER, QBIT_PASS. The "Send to qBit" button will then add magnets directly.

Troubleshooting

"Python is not recognized" / "command not found"

Install Python and (on Windows) tick "Add python.exe to PATH." On Mac/Linux try python3 instead of python.

The .command files won't run on Mac

Right-click → Open → Open. If that fails, in Terminal from the project folder run:

chmod +x install-mac.command start-mac.command

Windows saved my file as .env.txt

Turn on View → File name extensions in File Explorer and rename it back to .env.

It says required settings are missing on startup

The app needs PLEX_URL, PLEX_TOKEN, TVDB_API_KEY, and AUTH_PASSWORD in .env. Fill in whichever it names and start again.

I can't log in

Double-check AUTH_USERNAME / AUTH_PASSWORD in .env match what you're typing, and that you saved the file. If you changed them, restart the app.

A show shows episodes as missing that I actually have

The match relies on TheTVDB's episode numbering and your files being correctly matched in Plex. Very new episodes, specials (season 0 is skipped), or mismatched Plex metadata can cause discrepancies. Re-matching the show in Plex usually fixes it.

"Send to qBit" fails

Make sure the qBittorrent Web UI is enabled and the URL/username/password in .env are correct, and that qBittorrent is running.

Still stuck?

Open an Issue on the repo with your OS, what you did, and the exact error — happy to help.