If you run Plex, you've probably wondered who's actually watching what, how much bandwidth your library is chewing through, or why your server slows to a crawl every Friday night. Plex's own dashboard gives you almost nothing here — a handful of live stream stats and not much history. Tautulli fixes that gap. It sits next to your existing Plex server, quietly logging every play, pause, and transcode, and turns that data into graphs, watch history, and notifications you can actually use.
This guide walks through installing Tautulli inside its own lightweight LXC container on Proxmox VE, rather than bolting it onto the same container or VM that's already running Plex. Keeping the two separate means a Tautulli update or a crashed process never touches your media server, and you can restart or rebuild one without worrying about the other. Everything below was tested on Proxmox VE 8.x and 9.x using a Debian 12 container template.
What You Will Learn
- What Tautulli actually does and how it differs from Plex's built-in stats
- How to create a small, resource-light LXC container for it
- How to install Tautulli from source using Python's virtual environment
- How to run it as a proper systemd service that survives reboots
- How to connect it to your existing Plex server
- The permission mistake that trips up almost everyone on their first install
What Is This Feature?
Tautulli is a free, open-source monitoring and statistics tool built specifically for Plex Media Server. It doesn't replace Plex or stream any media itself — it just watches Plex's activity log and its API, and stores everything in a local database. From there it builds watch history per user, tracks which devices and apps people are streaming from, and shows you bandwidth and transcode load over time.
It also handles notifications. You can wire it up to send an alert to your phone, a Discord channel, or an email inbox whenever someone starts a stream, a new episode gets added to your library, or a Plex server goes offline. None of that comes from Plex itself.
An LXC container, if you're new to Proxmox, is a lightweight form of virtualization that shares the host's Linux kernel instead of emulating its own hardware like a full virtual machine does. That makes it start faster and use less RAM and disk than a VM running the same operating system. For something like Tautulli, which is a small Python application with modest resource needs, an LXC container is a natural fit — you don't need the overhead of a full VM just to run one background service.
Why Would You Use It?
Plex Pass gives you a "Plex Dashboard" with basic statistics, but it's shallow and disappears once you're not actively paying for Plex Pass. Tautulli is free forever, stores history locally on hardware you control, and goes much deeper.
A few concrete things it's good for:
- Seeing exactly who's watching what, and how often, without asking your family
- Spotting when a stream is transcoding instead of direct playing — usually the reason your server's CPU spikes
- Getting notified the moment a new movie or episode finishes downloading and shows up in Plex
- Auditing login history if you share your server outside your household
- Pulling monthly reports on your most-watched shows, without digging through Plex's own logs
Honestly, if you're the only person using your Plex server, you might not need most of this. But the moment you're sharing access with roommates, family, or friends, Tautulli earns its keep almost immediately — usually the first time someone asks "why is my stream buffering" and you can actually check.
Prerequisites
Before starting, make sure you have:
- A working Proxmox VE 8.x or 9.x installation with at least one node online
- An existing Plex Media Server, either running natively, in a VM, or in its own LXC container — it doesn't need to be on the same host, just reachable over the network
- A Debian 12 (bookworm) LXC template downloaded, or access to pveam to fetch one
- Root or sudo access on the Proxmox host
- About 10 minutes, plus a few more if the template needs downloading
You don't need much in the way of resources. Tautulli itself is a small Python process — 1 CPU core and 512 MB of RAM is more than enough, and it uses well under 1 GB of disk once installed.
Step-by-Step Tutorial
Step 1: Download the Debian 12 template (if you don't already have one)
Log in to the Proxmox web interface, click your node in the left sidebar, then go to local storage and open the CT Templates tab. Click Templates, search for debian-12-standard, and download it. Or from the shell:
pveam update
pveam available | grep debian-12
pveam download local debian-12-standard_12.7-1_amd64.tar.zstThe exact filename changes as Debian releases point updates, so check the output of the second command if the third one 404s.
Step 2: Create the LXC container
You can do this from the GUI with Create CT, or from the shell with pct create. The shell version is faster to repeat if you ever rebuild it:
pct create 220 local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
--hostname tautulli \
--cores 1 \
--memory 512 \
--swap 512 \
--rootfs local-lvm:4 \
--net0 name=eth0,bridge=vmbr0,ip=dhcp \
--unprivileged 1 \
--features nesting=1 \
--onboot 1Change 220 to whatever VMID is free on your setup, and swap local-lvm for whatever storage you actually use for container root disks. A 4 GB root disk is plenty here — Tautulli's own database rarely grows past a few hundred megabytes even after years of history.
Start the container and open its console:
pct start 220
pct enter 220Step 3: Update the container and install dependencies
Inside the container shell:
apt update && apt full-upgrade -y
apt install -y git python3 python3-venv python3-pip curlThis pulls in Python 3, its virtual environment tool, pip for installing Python packages, and git so you can clone Tautulli's source directly from GitHub.
Step 4: Create a dedicated user and clone Tautulli
Running Tautulli as root works, but it's bad practice — if the app is ever compromised, root access makes the damage much worse. Create a low-privilege system user instead:
useradd -r -s /usr/sbin/nologin tautulli
mkdir -p /opt/Tautulli /var/lib/tautulli
git clone https://github.com/Tautulli/Tautulli.git /opt/TautulliStep 5: Set up the Python virtual environment
A virtual environment keeps Tautulli's Python packages separate from the system's Python install, so an update to one doesn't break the other.
cd /opt/Tautulli
python3 -m venv venv
venv/bin/pip install --upgrade pip
venv/bin/pip install -r requirements.txtThis step takes a minute or two depending on your connection — it's downloading and compiling a handful of Python packages.
Step 6: Fix ownership and create the systemd service
chown -R tautulli:tautulli /opt/Tautulli /var/lib/tautulliNow create the service file:
cat <<'EOF' > /etc/systemd/system/tautulli.service
[Unit]
Description=Tautulli
After=network.target
[Service]
Type=simple
User=tautulli
Group=tautulli
WorkingDirectory=/opt/Tautulli
ExecStart=/opt/Tautulli/venv/bin/python3 /opt/Tautulli/Tautulli.py --nolaunch --datadir /var/lib/tautulli
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
EOFReload systemd and start it:
systemctl daemon-reload
systemctl enable --now tautulliStep 7: Check that it's running and open the web UI
systemctl status tautulliYou should see active (running) in green. If so, find the container's IP with ip a or check it in the Proxmox GUI under the container's Summary tab, then open a browser to:
http://<container-ip>:8181That loads Tautulli's first-run setup wizard.
Step 8: Connect Tautulli to your Plex server
The setup wizard asks you to sign in with your Plex.tv account, which lets it auto-discover any Plex servers tied to that account and pull in the connection details automatically. If you'd rather not sign in, you can enter the Plex server's address manually — it's usually http://<plex-ip>:32400 — along with your Plex authentication token, which you can find under any library item's Get Info → View XML link in Plex, in the URL as the X-Plex-Token parameter.
Once connected, walk through the rest of the wizard: pick which libraries to monitor, decide whether you want notification agents set up now or later (you can always add these afterward under Settings → Notification Agents), and finish. Tautulli starts pulling history from Plex's own logs immediately, so you'll see some backdated activity show up on the dashboard right away.
Commands Explained
| Command | What it does |
|---|---|
pveam download | Downloads a container template from Proxmox's template repository onto local storage |
pct create | Creates a new LXC container from a template, with the resources and network settings you specify |
pct enter | Drops you straight into a root shell inside the container, without needing SSH |
useradd -r -s /usr/sbin/nologin | Creates a system account that can own files and run services, but can't be used to log in interactively |
python3 -m venv venv | Creates an isolated Python environment in a folder called venv, so installed packages don't collide with the system's Python |
systemctl enable --now | Enables a service to start on boot and starts it immediately in the same command |
Common Errors
"ModuleNotFoundError" when starting Tautulli.py directly — this almost always means you ran the command with the system Python instead of the one inside venv. Always call /opt/Tautulli/venv/bin/python3, not just python3, or the interpreter won't see the packages you installed.
Web UI never loads on port 8181 — check that the service actually started with systemctl status tautulli. If it's stuck in a restart loop, run journalctl -u tautulli -n 50 to see the actual Python traceback instead of guessing.
Permission denied writing to /var/lib/tautulli — this is the mistake almost everyone hits on their first try. It happens when you create the data directory as root, forget the chown step, and then run the service as the tautulli user. Fix it with chown -R tautulli:tautulli /var/lib/tautulli and restart the service.
Tautulli connects but shows no history — double check the Plex token is current. Tokens can be invalidated by signing out of Plex apps or resetting the server's identity, and Tautulli will fail silently on some pages instead of throwing a clear error.
Troubleshooting
If Tautulli won't start at all, the fastest path to an answer is the systemd journal:
journalctl -u tautulli -fThe -f flag follows the log in real time, so you can watch it fail as you restart the service in a second terminal window with systemctl restart tautulli.
If the web UI loads but activity never appears, check Tautulli's own logs under Settings → Help → Logs in the web interface, or directly at /var/lib/tautulli/logs/tautulli.log inside the container. Most connection issues show up there as a clear HTTP error against the Plex server's address.
If the container can't reach Plex over the network at all, ping the Plex server's IP from inside the Tautulli container first:
ping -c 3 <plex-ip>No response usually points to a firewall rule or VLAN mismatch between the two containers rather than anything wrong with Tautulli itself.
Best Practices
- Keep Tautulli in its own container, separate from Plex. It makes backups, updates, and troubleshooting far simpler when the two aren't tangled together.
- Back up
/var/lib/tautullibefore any update — that's where the config and the watch-history database live, and there's no built-in way to regenerate lost history. - Use Proxmox's own backup jobs (vzdump) against the container rather than relying on Tautulli's internal database export alone. A full container backup covers the OS, the venv, and the data in one shot.
- Set a reasonable data retention window under Settings → General if you're monitoring a busy shared server — the history table grows slowly, but it does grow.
- Don't expose port 8181 directly to the internet. If you want remote access, put it behind a reverse proxy with authentication, the same way you'd protect any other internal dashboard.
Frequently Asked Questions
Does Tautulli need to run on the same machine as Plex?
No. It just needs network access to Plex's API port, which defaults to 32400. Running it in a separate container is the more common setup.
Will Tautulli slow down my Plex server?
Not noticeably. It polls Plex's API periodically and reads its logs — it doesn't touch the actual media streams.
Can I monitor more than one Plex server with a single Tautulli instance?
No, each Tautulli instance tracks one Plex server. If you run multiple Plex servers, you'll need a separate Tautulli container for each.
Is there a Docker option instead of installing from source?
Yes, Tautulli publishes an official Docker image. If you already run Docker inside an LXC container on Proxmox, that's a valid alternative to the source install covered here.
How do I update Tautulli later?
Stop the service, run git pull inside /opt/Tautulli as the tautulli user, reinstall requirements with the venv's pip, then start the service again. Tautulli also shows an update notice in its own web UI when a new version is available.
Conclusion
Once Tautulli is running, you'll probably check it more than you expect. It's the kind of tool that answers questions you didn't know you had — why last night's stream buffered, who's actually still using the account you set up for a friend two years ago, whether your library grew the way you thought it did this month. None of that changes how Plex itself works; it just gives you visibility you didn't have before.
The container you built here is small and disposable. If you ever want to start over, tearing it down and repeating these steps takes less time than reading through this guide did.