How to Monitor Your Plex Server with Tautulli

Plex's built-in dashboard tells you who is streaming right now. Tautulli tells you everything else: what was streamed last month, which users consume the most bandwidth, what content sits unwatched, and when your server is under the heaviest load. It is the single most useful companion tool for any Plex server administrator, and it is completely free and open source.

What Is Tautulli

Tautulli (formerly PlexPy) is a Python-based monitoring application that connects to your Plex Media Server and records detailed playback statistics. It runs as a lightweight web application alongside your Plex server and provides a dashboard, historical analytics, notification triggers, newsletter generation, and custom scripting capabilities.

Tautulli does not interact with your media files or modify your Plex installation in any way. It reads data from the Plex API (the same API we cover in our Plex API guide) and stores historical records in its own SQLite database. Your Plex server does not even know Tautulli exists.

Installation

Docker (Recommended)

The easiest and most portable installation method is Docker. Pull the official image and run:

docker run -d \
  --name tautulli \
  --restart unless-stopped \
  -p 8181:8181 \
  -v /path/to/tautulli/config:/config \
  ghcr.io/tautulli/tautulli

Replace /path/to/tautulli/config with a directory on your host where Tautulli should store its configuration and database. After the container starts, access the web interface at http://your-server-ip:8181.

If you use Docker Compose, add Tautulli to your existing stack:

services:
  tautulli:
    image: ghcr.io/tautulli/tautulli
    container_name: tautulli
    restart: unless-stopped
    ports:
      - "8181:8181"
    volumes:
      - /path/to/tautulli/config:/config

Bare Metal (Linux)

If you prefer running Tautulli directly on the host, clone the repository and run it with Python:

git clone https://github.com/Tautulli/Tautulli.git /opt/tautulli
cd /opt/tautulli
python3 Tautulli.py

To run Tautulli as a systemd service that starts on boot, create a unit file at /etc/systemd/system/tautulli.service and enable it with systemctl enable tautulli.

Windows and macOS

Tautulli provides standalone installers for Windows (MSI) and macOS (DMG) on their GitHub releases page. Download, install, and the setup wizard will guide you through connecting to your Plex server.

Initial Configuration

On first launch, Tautulli's setup wizard asks for two things: your Plex server connection details and your Plex account credentials. If Tautulli runs on the same machine as Plex, the connection URL is http://localhost:32400. If they are on different machines, use the Plex server's IP address.

Tautulli will authenticate via your Plex account and begin importing your existing watch history. Depending on the size of your library and history, this initial import can take anywhere from a few seconds to several minutes. Once complete, the dashboard will populate with current and historical data.

Key Statistics and What They Tell You

Activity Dashboard

The main dashboard shows real-time streams with details including the user, media title, playback state, stream type (Direct Play, Direct Stream, or Transcode), bandwidth usage, and client device. This is similar to the Plex dashboard but with more detail and historical context.

Watch Statistics

The statistics page breaks down viewing habits by user, time period, content type, and platform. You can answer questions like: Which user watched the most content last month? What percentage of plays are transcoded vs. Direct Play? What day of the week sees the heaviest usage? Which library gets the most activity?

History

Tautulli logs every single play session with granular detail: when it started, when it stopped, whether it was paused, how much of the item was watched, the stream type, the bandwidth consumed, and the client used. This history is searchable and exportable, making it invaluable for troubleshooting ("when did the buffering start?") and capacity planning ("do I need more upload bandwidth?").

Graphs

Visual graphs show plays over time, bandwidth over time, concurrent streams, and duration statistics. These help identify trends like increasing usage, peak hours, and whether your server's capacity is keeping up with demand.

Notification Setup

Tautulli can send notifications for virtually any event. Supported notification agents include:

• Discord: Post to a channel via webhook. The most popular option for self-hosters who use Discord for server management.
• Email: SMTP-based email notifications with customizable templates.
• Telegram: Send notifications to a Telegram bot.
• Slack, Pushover, Pushbullet: Additional messaging platforms.
• Custom scripts: Run any script or program when an event fires.

Setting Up Discord Notifications

1. In Discord, go to your server settings, then Integrations, and create a new Webhook. Copy the webhook URL.
2. In Tautulli, go to Settings > Notification Agents and click "Add a new notification agent."
3. Select Discord, paste the webhook URL, and configure which events should trigger notifications.
4. Customize the message template. Tautulli supports rich formatting with variables like {user}, {title}, {stream_decision}, and dozens more.

Common notification triggers include: playback started, playback stopped, buffer warning, new content added, Plex server down, and Plex server back up. The "Plex server down" notification is particularly valuable -- it alerts you immediately when your server goes offline so you can investigate before users complain.

Newsletters

Tautulli can generate and send HTML newsletters summarizing recent additions to your Plex library. This is a great way to keep your shared users engaged and aware of new content without requiring them to check Plex regularly.

Configure newsletters under Settings > Newsletters. You can set a schedule (weekly or monthly), customize the template with your own branding, and choose which libraries to include. The newsletter is sent via email to all users or a custom list of recipients.

Custom Scripts

For advanced automation, Tautulli can execute custom scripts when events occur. The script receives event data as command-line arguments or environment variables. Example use cases:

• Kill transcoded streams. If a user forces a transcode on content that should Direct Play, automatically stop the stream and notify them to adjust their client settings.
• Bandwidth enforcement. Monitor concurrent streams and pause lower-priority streams when total bandwidth exceeds your upload capacity.
• Usage-based access. Track inactive users and automatically revoke library access after a defined period of inactivity.
• Integration with home automation. Trigger smart home events (dim lights, turn on the TV) when playback starts on a specific device.

User Monitoring and Management

Tautulli provides per-user profiles showing their complete watch history, most-watched content, average session duration, preferred client devices, and streaming quality. This is useful for managing shared servers where you want to understand usage patterns without manually interrogating each user.

Combined with notification triggers, you can build a system that alerts you to unusual activity (a user suddenly streaming 24/7), capacity issues (too many simultaneous transcodes), or misconfigurations (a user's client forcing unnecessary transcodes).

Tautulli is one of those tools that you install once, configure in 15 minutes, and then wonder how you ever managed your Plex server without it. The insights it provides transform server administration from guesswork into data-driven decision making.

Related Articles