Tautulli: monitoring and analytics for a Plex Media Server

What Tautulli records that Plex itself does not

Plex Media Server shows what is streaming right now. It is not built to answer who watched a given film three weeks ago, on which device, from which IP address, or how many times a shared user has rewatched a series. Tautulli is a separate application that connects to the server and keeps that record itself.

The README lists the scope: current activity, global watching history with search and filtering, a full user list with comparison statistics, individual user pages including devices and IP addresses, complete library statistics and media file information, and sync list data for every user syncing items. Analytics are drawn with Highcharts. There is no separate web server to configure, which is the practical reason it is often run next to Plex on the same box.

The audience is narrow and specific. It is for the person who administers the Plex server: the one who gets asked why a stream stopped, who wants to know whether a remote user is transcoding, or who wants an email when a new episode lands. It is not a media player, not a library manager, and it does not replace Plex's own sharing controls.

How Tautulli gets its data from Plex

Tautulli is a CherryPy web application (cherrypy and cheroot are both pinned in requirements.txt) that talks to Plex through the plexapi library, also pinned there. The data flow is one-directional: Tautulli polls and subscribes to the Plex server, writes what it observes into its own database under the data directory, and serves that database back through its web interface.

That design has consequences worth naming. The history lives in Tautulli, not in Plex, so a fresh Tautulli install starts with an empty history even on a server that has been running for years. The scheduled work is handled by apscheduler, which is how periodic tasks such as statistics refreshes and newsletter generation are queued. Notifications fan out through a long list of client libraries in requirements.txt: paho-mqtt for MQTT, python-twitter, musicbrainzngs, cloudinary, and gntp, which the file notes was manually patched for Python 3.13.

The repository also ships API.md, so the collected data is reachable programmatically rather than only through the browser. The search results show people asking for a Tautulli API key, and the API document is where that is described. If you plan to build a dashboard of your own, that file is the entry point, not the web UI.

Installing Tautulli with Docker and reaching the web interface

The README does not spell out install commands. It points to the Installation Guides on tautulli.com and shows a status table with separate release channels for master, beta and nightly across Docker, Snap and Windows/macOS installers. The repository does contain a Dockerfile, and it is short enough to read directly.

The image is built from ghcr.io/tautulli/tautulli-baseimage:python3, copies the application into /app, creates a tautulli user with UID and GID 1000, and declares /config as a volume. The container command is python Tautulli.py --datadir /config, so all persistent state, including the database and configuration, belongs on that volume. The exposed port is 8181.

Running the container therefore means mapping port 8181 and mounting a directory onto /config, which is what keeps your history across container upgrades. The Dockerfile also defines a health check that curls https://localhost:8181/status, falling back to http, with a 90 second start period. That tells you two things: the service answers on /status, and it may serve HTTPS on the same port. After the container reports healthy, open http://your-host:8181 in a browser and work through the setup wizard, which is where you enter the Plex server details. The README's preview gallery is on tautulli.com if you want to see the interface before installing.

The Dockerfile sets TAUTULLI_DOCKER=True and TZ=UTC. If your notifications or statistics look time-shifted, TZ is the environment variable to change at run time.

Where Tautulli is the wrong tool

The most common mismatch is the media server itself. Tautulli is written against Plex Media Server, and the README describes it that way throughout. The related searches include Tautulli Jellyfin and tautulli for jellyfin, which suggests people look for it there, but nothing in the repository claims Jellyfin support. If you run Jellyfin, this is not your monitoring tool.

The second limitation is historical. Because Tautulli stores its own records, the analytics only cover the period since it was first installed and connected. There is no documented backfill from Plex. Anyone expecting years of retroactive statistics on a long-running server will be disappointed on day one.

Third, notifications are only as good as the transport you configure. The dependency list shows a wide range of clients, and the README calls notifications "fully customizable," but each transport has its own authentication and its own failure modes. A misconfigured notifier can fail silently from the user's point of view, and the README does not document retry behaviour for failed deliveries. Treat notification setup as something to verify with a test trigger rather than assume.

Finally, there is the branch question. The default branch in this repository is nightly, while releases are cut from master. If you clone the default branch you are on the nightly line, not the release line. The README's own table separates master, beta and nightly builds for a reason.

Tautulli against Plex Dash and Plex's own activity view

The natural alternative is Plex's own tooling: the activity panel inside Plex Web and the Plex Dash mobile app. Both show live sessions and basic server status, they come from Plex itself, and they require nothing extra to run. The difference in approach is where the record lives. Plex's views are about the present; they are not a searchable archive with per-user comparison statistics and library-level reporting.

Tautulli's approach is to be that archive. It maintains its own database, its own user pages with device and IP history, and its own graphing layer. That is more to run and more to back up, and it introduces a second place where your viewing data exists. In exchange you get queries Plex does not answer, an HTTP API documented in API.md, and notification rules that fire on stream activity or recently added media.

For a single-user server with no sharing, the trade is usually not worth it. For a server with remote users, the per-user history and device/IP detail are the reason people install it in the first place.

Licence, upgrade path and the cost of keeping it running

Tautulli is licensed under GPL-3.0. If you run it as a service next to your Plex server, that is the ordinary case and nothing about it is unusual. The licence matters if you intend to redistribute a modified version or bundle it into a product; GPL-3.0 carries obligations in that scenario. This is a description of the licence identifier, not legal advice, and anyone shipping it should read LICENSE in the repository.

Upgrade cost is mostly the container or package you installed. Docker images are published per branch, so pulling latest, beta or nightly determines how much churn you accept. The pinned requirements.txt shows the project tracks its dependencies tightly (cherrypy 18.10.0, plexapi 4.18.2, requests 2.34.2, and so on), which reduces surprise but also means upgrades arrive in batches with the application rather than independently.

Two operational details are worth planning for. The /config volume holds the database and configuration, so it is the thing to back up; losing it means losing the history, since Plex does not hold a copy. And the health check's 90 second start period suggests the application is not instant to come up, which matters if you put it behind a reverse proxy with an aggressive timeout.

Editorial conclusion

Adopt Tautulli if you run a Plex Media Server and want a local record of who watched what, plus notifications you control. Skip it if you run Jellyfin, or if you want a hosted service with no server to maintain. Before deploying, confirm which branch you are pulling (master, beta or nightly), that port 8181 is reachable only where you want it, and that your Python is 3.10 or newer.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. Tautulli/Tautulli on GitHub