How to Use Jellystat: The Beginner’s Guide (First Deploy, the API-Key Rule, First Sync, and the Library-Stats Lesson)

CodexFuse Team · 2026-11-02T06:24:38.555Z · 13 min read min read

Learn how to use Jellystat, the free open-source stats app for Jellyfin: Docker deploy, the API-key rule, first sync, dashboard tour, watch history, and backups.

Learning how to use Jellystat starts with a one-sentence correction that saves every beginner the same confusion: Jellystat is a stats app for Jellyfin, not a media server. It does not stream movies, it does not host your files, and it is not Jellyfin itself — it sits next to your Jellyfin server, reads what it is doing through an API key, and turns the raw events into the answers Jellyfin's own interface never shows you: who watched what, when, on which device, and which corners of your library are gathering dust.

One more disambiguation before we start, stated once: this jellystat tutorial is about CyferShepard/Jellystat, the free and open-source statistics app for Jellyfin. A different commercial product at jellystat.com sells website and app analytics — different company, different product, not this guide.

If you are new to the server side of the equation, start with our Jellyfin beginner guide first — Jellystat reports on a Jellyfin server you already run, and everything below assumes you have one. The deploy is a Docker Compose stack, the setup is one API key and one connection, and the payoff is a dashboard of your household's actual watching habits.

What Is Jellystat, Exactly?

Jellystat is a free and open source Statistics App for Jellyfin. That line is the project's own description of itself on GitHub, and it is exactly right: Jellystat watches your Jellyfin sessions live, keeps a permanent record of every play, and rolls it all into per-user activity, per-library statistics, and watch history. It is open source under the MIT license, it runs as a self-hosted web app on your own hardware, and your stats never leave your network. Roughly 2,500 GitHub stars back that description — the count moves daily, but the shape of the project is settled.

Two honest facts sit next to that definition. First, Jellystat covers Jellyfin and Emby — not Plex (see the Tautulli comparison below). Second, the maintainer posted a PROJECT UPDATE announcing a from-scratch rebuild on a more modern architecture, which means the current version is stable but in maintenance mode: new features are paused while major bug fixes continue. Practically, nothing in this guide depends on a moving target — the deploy, the API key, and the dashboard all work as documented below.

What Do You Need Before You Install Jellystat?

You need three things, and nothing else: a Jellyfin server that is already running and reachable on your network, Docker and Docker Compose on the machine that will host Jellystat, and the patience to let the first sync finish. That machine can be the same box that runs Jellyfin, a home NAS, a homelab server, or a small VPS — if you are renting servers for the first time, our what is VPS hosting guide explains the model before you spend a dollar.

Check your Jellyfin version while you are there. The latest stable line is the 12.x series (12.3 at the time of writing), and the 12.0 release notes warned users to remove third-party plugins before upgrading, because plugins built for 10.11 would not load on 12.0 until their authors rebuilt them. Jellystat connects through Jellyfin's API rather than as a plugin, so it sidesteps that breakage — but keeping the server itself current is still the right habit.

How Do You Deploy Jellystat with Docker?

The jellystat docker install is the official two-container stack from Docker Hub: the Jellystat app plus its own Postgres database, because your watch history is a real database and deserves one. The whole stack is one file. Create a folder called jellystat, save this as docker-compose.yml — it is the official example from the cyfershepard/jellystat Docker Hub page, shipped values included:

version: '3'
services:
  jellystat-db:
    image: 'postgres:15.2'
    shm_size: 1gb
    container_name: jellystat-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: mypassword
    volumes:
      - 'postgres-data:/var/lib/postgresql/data'
  jellystat:
    image: 'cyfershepard/jellystat:latest'
    container_name: jellystat
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: mypassword
      POSTGRES_IP: jellystat-db
      POSTGRES_PORT: 5432
      JWT_SECRET: my-secret-jwt-key
      TZ: mytimezone
    volumes:
      - 'jellystat-backup-data:/app/backend/backup-data'
    ports:
      - '3000:3000'
    depends_on:
      - jellystat-db

The image to pull is cyfershepard/jellystat, and the tag to use is latest — the project ships rolling releases, so pinning a version number from memory is a losing game; check the GitHub releases page if you ever need a specific one. Here is what each environment variable in that file does:

With the file saved, the jellystat setup runs in five steps:

1. Replace mypassword and my-secret-jwt-key with your own values. The official example ships placeholders, and real credentials are the difference between a dashboard and an incident. Never reuse your Jellyfin password here.
2. Set TZ to your timezone.
3. Run docker compose up -d in that folder and wait for both containers to report healthy.
4. Open http://<your-server-ip>:3000 in a browser. Whoever opens Jellystat first creates the admin account, so do this step yourself, immediately — do not leave a fresh install sitting open.
5. Log in with the account you just created. You now have an empty dashboard and one job left: pointing it at Jellyfin.

If the Compose syntax is new to you, our Docker beginner guide covers containers from zero — this guide assumes that part is handled.

How Do You Create the Jellyfin API Key for Jellystat?

This is the API-key rule, stated once and worth following exactly: Jellystat connects to Jellyfin with an API key, never with your Jellyfin admin password. A password shared with a second app is a password you cannot revoke on its own; an API key is created per app, and you can delete it from Jellyfin's dashboard any time without touching your login.

Creating the jellystat jellyfin api key takes about a minute. In Jellyfin: open your Jellyfin instance, click Dashboard in the sidebar, click API Keys, click the + icon, type Jellystat as the app name, and click Ok. Jellyfin generates the key immediately — copy it somewhere safe right away, because you will paste it into Jellystat in the next step. A second independent source documents the same flow under Dashboard, Advanced, API Keys, so if your Jellyfin layout looks slightly different, check the Advanced section.

One honest limitation: Jellyfin's documented flow creates the key per app name, and today's official documentation describes no granular per-key permission scopes — so take it for what it is, an app-level token revocable from Dashboard, API Keys, and move on.

How Do You Connect Jellystat to Jellyfin?

Back in Jellystat's web UI, the connection screen asks for two things: your Jellyfin address and the API key you just created. Type the same Jellyfin address your devices use — the NAS or server IP with port 8096, for example http://192.168.1.20:8096 — paste the API key, and click Save Jellyfin Details. Once the connection saves, the jellystat setup is effectively done; everything from here is the app doing its job.

The one networking detail beginners miss: the Jellystat container cannot reach Jellyfin through your laptop's localhost, so if Jellyfin runs on the same machine as Docker, use that machine's LAN IP, not localhost. The moment the details save, Jellystat starts its first library sync automatically.

What Happens During the First Jellystat Sync?

The first sync is Jellystat importing your entire Jellyfin library — every movie, episode, and song it can see — so its statistics have something to count. It runs automatically after you connect, and the project publishes no timing guidance for it, so the honest expectation is this: the initial import is the longest single step in this whole guide, and a large library will simply take a while. Let it run; the dashboard fills in as items arrive.

After that first import, the jellystat sync stays automatic: new library items and new plays are picked up on their own, and the watch-history side of the product keeps a permanent record without you touching anything again. Syncing is a background habit of the app, not a chore on your list.

What Does the Jellystat Dashboard Show You?

The dashboard is the payoff — the jellyfin stats question Jellyfin itself never answers. Not what you own, but what your household actually watches: which user re-watches the same show, which movies sit unwatched for a year, which device does the heavy lifting. That is the whole product. Here is the tour, panel by panel, matching the features the project lists in its README:

If your mental image of a jellyfin statistics dashboard was "Jellyfin, but with charts," this is close — except Jellystat's charts are about behavior, not files. Spend your first week checking the Activity view after movie night; it is the fastest way to learn what the app knows.

Jellystat vs Tautulli: What's the Difference?

The short version, quoted from HowToGeek: Jellystat is "like Tautulli, but for Jellyfin." The long version is one line each: Tautulli is the established stats-and-monitoring web app for Plex Media Server, and it works only with Plex. Jellystat is the equivalent for Jellyfin (and Emby), and it works only with Jellyfin and Emby. If your server is Plex, you want Tautulli; if it is Jellyfin, you want Jellystat; running both servers means running both dashboards.

This is also why Jellystat gets its own guide and Tautulli stays a comparison member on this page: they are different products for different servers, and neither is a substitute for the other. The jellystat vs tautulli question ends the moment you know which server you run.

How Do You Back Up Your Jellystat Data?

Your Jellystat database holds your history — every play, every user stat, everything the dashboard shows. Say it once, plainly: lose the database, lose the history. Jellystat stores that history in its own Postgres database (named jfstat by default), and the app container keeps its backup files at /app/backend/backup-data, which the official compose file already mounts as a persistent volume.

Back up two things. First, the postgres-data volume — if your NAS or host runs scheduled backups, include it; it is the live history. Second, use Jellystat's own export: open Settings, then Backup, keep only Activity selected, run the Backup Jellystat task, and download the JSON file it produces. That export gives you a portable copy of your history you can keep anywhere, and it is the file you would reach for if you ever moved Jellystat to a new machine.

7 Beginner Mistakes in Jellystat

Sources

1. github.com/CyferShepard/Jellystat — project description ("Jellystat is a free and open source Statistics App for Jellyfin"), MIT license, release history, and the PROJECT UPDATE rebuild notice
2. hub.docker.com/r/cyfershepard/jellystat — the official docker-compose example, image name, and default port 3000
3. mariushosting.com — How to Install Jellystat on Your Synology NAS: the API-key creation steps and the Jellyfin connection flow
4. techbloat.com — Jellyfin API key guide: the same key flow under Dashboard, Advanced, API Keys
5. howtogeek.com — Jellystat overview: "like Tautulli, but for Jellyfin"
6. tautulli.com — Tautulli's own description: monitoring and analytics for Plex Media Server
7. docs.tracearr.com — multi-server comparison: Tautulli is Plex-only, Jellystat is Jellyfin/Emby-only
8. corelab.tech — JellyWatch review: generating a Jellyfin API key is the more secure connection
9. forum.jellyfin.org — Jellyfin Server Web release 12.3: the current stable line
10. windowsforum.com — Jellyfin 12 coverage: third-party plugins built for 10.11 do not load on 12.0
11. notebookcheck.net — Jellyfin 12: third-party plugins need rebuilding against .NET 10
12. YouTube — "Jellyfin + 5 Free Upgrades = Your Own Netflix (2026)": the first person to open Jellystat creates the admin account

Frequently Asked Questions

Is Jellystat free?

Yes. Jellystat is free and open source under the MIT license, and every part of this guide — the Docker stack, the API key, the dashboard — costs nothing beyond the machine you run it on.

Does Jellystat work with Plex?

No. Jellystat works with Jellyfin and Emby only. The Plex equivalent is Tautulli — different product, same idea — and running both servers means running both dashboards.

Do I have to give Jellystat my Jellyfin password?

No, and you should not. Create a per-app API key in Jellyfin's dashboard under API Keys, name it Jellystat, and paste the key instead. You can revoke it any time without changing your password.

Where is my Jellystat watch history stored?

In Jellystat's own Postgres database (named jfstat by default), not in Jellyfin. That makes the database your history's home: back up the postgres-data volume and use Settings, Backup in the app to export Activity as JSON.

Is Jellystat still being developed?

Sort of. The maintainer announced a from-scratch rebuild on a more modern architecture, so new features are paused while the rebuild is underway — but the current version is stable, and major bug fixes are still being pushed. Everything in this guide works with the documented release.