Your hardware, your media, your rules. This is the DIY path — expect a bit of terminal work and about an hour the first time. When you're done, your library streams to any of your screens, anywhere, and you can invite family with an email address.
Everything else — Python, FFmpeg, dependencies — the install script sets up for you.
Linux (Ubuntu/Debian) — recommended for an always-on server. From the code folder:
It installs the system packages (Python, FFmpeg, and friends), walks you through port / TMDB key / media folders interactively, sets NotPlex up as a service that starts on boot, opens the firewall port, and starts it. Re-run the same script any time to update.
Windows. From the code folder, in PowerShell:
It checks Python, installs FFmpeg automatically if it's
missing, sets up the environment, creates a starter .env
(edit it to add your TMDB key), and starts the server. To keep it running
after reboots, add the script to Task Scheduler.
backend/, pip install -r
requirements.txt, put PORT, TMDB_API_KEY, and
MASTER_API_URL=https://notplex.app in a .env, install
FFmpeg, and run python main.py.Open http://localhost:6969 in a browser and sign in with your notplex.app account. The first account to sign in becomes the server's admin — that's you. From then on, only invited users can access it.
In the web UI, create a library per collection — one for Movies, one for TV Shows — pointing each at a folder. Then hit Scan: NotPlex walks the files, matches them on TMDB, and pulls posters, descriptions, cast, and ratings automatically. Scans re-run on a schedule after that.
The scanner is happiest with conventional naming:
| Type | Works well |
|---|---|
| Movie | Interstellar (2014).mkv |
| TV episode | Show Name S01E05.mkv · Show.Name.1x05.mkv |
| Daily show | Show Name 2026.08.17.mkv |
Keep each show's episodes inside a folder named after the show. Most "scene-style" names work fine as-is.
/media — the install script offers to symlink your real
media folders there (e.g. /media/movies → /mnt/storage/movies).In the server's web UI, go to Settings and register the instance with notplex.app. That's what makes your server appear automatically on your (and later your family's) TVs, browsers, and dashboard. It also starts a heartbeat so notplex.app knows the server is online.
For access away from home, forward your chosen port (TCP 6969 in this guide) to the server's LAN IP on your router. On your home network everything works without this — devices take a direct local path automatically.
In the web UI, open a library and share it by email. The person creates a free notplex.app account with that exact address, and your server appears on their devices — send them the getting-started guide and you're done. You can see and revoke access anytime from your dashboard.
That's FFmpeg missing or not on the PATH — browsers need some formats transcoded. Re-run the install script (it installs FFmpeg), then restart the server.
Check the TMDB API key in your .env. Odd file names can also fail to match — rename toward the table above and re-scan.
The port forward isn't reaching the server — re-check the router rule points at the right LAN IP and port, and that the server machine's firewall allows the port.
The email you shared with must exactly match the email on their notplex.app account. Re-share with the right address; it shows up within a minute.