Jellyfin User Guide

Jellyfin is the free, open-source, self-hosted media server. You point it at the movies, TV shows, music, books, and photos you already own, and it organizes them into a polished, Netflix-style library that you can stream to any device on your network — or, if you choose, over the internet. There is no subscription, no tracking, no premium tier, and no phoning home. Your media and your server belong entirely to you.

This guide walks you through installing Jellyfin, completing the first-time setup, organizing your media so Jellyfin recognizes it, and using every day-to-day feature: playback, user accounts, remote access, Live TV, plugins, and more. Architecture, deployment hardening, the full configuration reference, and the REST API live in the companion Admin Guide; this guide links there whenever a topic crosses into administration.

Note

This guide documents Jellyfin 12.0.0, built on .NET 10. Jellyfin runs on Linux, Windows, macOS, FreeBSD, Docker, and a range of NAS and single-board devices. The web interface looks and behaves identically across all of them.

1. Quick Start

If you just want to get a server running in five minutes, use Docker. This is the fastest path and the one the project itself ships templates for.

docker run -d \
  --name jellyfin \
  --user 1000:1000 \
  --net=host \
  --volume /path/to/config:/config \
  --volume /path/to/cache:/cache \
  --mount type=bind,source=/path/to/media,target=/media \
  --restart=unless-stopped \
  jellyfin/jellyfin:latest

Unable to find image 'jellyfin/jellyfin:latest' locally
latest: Pulling from jellyfin/jellyfin
...
Status: Downloaded newer image for jellyfin/jellyfin:latest
3f9c2b1e7a8d4c5f6e0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b

Now open a browser to http://<server-ip>:8096 and follow the setup wizard described in Section 4.

Tip

--net=host lets Jellyfin auto-discover clients and respond to LAN broadcasts. If you cannot use host networking, map ports 8096 (HTTP) and, optionally, 8920 (HTTPS) and 7359/udp (auto-discovery) explicitly. See Section 3.

The three volumes matter:

• /config — your settings, database, metadata, and logs. Back this up.
• /cache — transcodes, image cache, and other regenerable data.
• /media — your actual movie/TV/music files, mounted read-only is fine.

Important

The :latest tag tracks the newest stable release. For a server you depend on, pin a specific version tag and update it deliberately so you control when upgrades happen.

2. What Jellyfin Does

Jellyfin is a server plus a family of client apps. The server:

• Scans folders of media files you already have.
• Identifies each item and downloads matching metadata — posters, descriptions, cast, ratings, episode summaries — from internet providers.
• Presents everything through a web interface and a documented API.
• Transcodes media on the fly when a client cannot play the original format, so the same file streams to a 4K TV, a phone on cellular, and an old browser.
• Manages multiple user accounts, each with their own watch history, parental controls, and permissions.

The clients are the apps you watch with: the built-in web client (any browser), plus native apps for Android, Android TV, iOS, Roku, Fire TV, Kodi, and more, many of them community-built against the same API.

   Your media files                Jellyfin Server                 Clients
 ┌───────────────────┐          ┌────────────────────┐         ┌──────────────┐
 │ /media/Movies     │          │  Scan + identify   │         │  Web browser │
 │ /media/Shows      │ ───────► │  Metadata + images │ ──────► │  Phone / TV  │
 │ /media/Music      │          │  Stream / transcode│         │  Roku / Kodi │
 └───────────────────┘          └────────────────────┘         └──────────────┘

Note

Jellyfin never modifies your media files during normal operation. It reads them, and it writes metadata sidecar files only if you explicitly enable that option per library (see Section 6).

3. Installation

Jellyfin distributes official builds for most platforms. Pick the tab matching your environment.

3.1 Choosing an installation method

3.2 Install steps

Docker (compose)

Create a docker-compose.yml:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    user: 1000:1000
    network_mode: host
    volumes:
      - /path/to/config:/config
      - /path/to/cache:/cache
      - /path/to/media:/media
    restart: unless-stopped

Bring it up:

docker compose up -d

[+] Running 1/1
 ✔ Container jellyfin  Started

Debian / Ubuntu

sudo apt update
sudo apt install jellyfin

Setting up jellyfin (12.0.0) ...
Created symlink /etc/systemd/system/multi-user.target.wants/jellyfin.service

The service starts automatically and is managed by systemd:

sudo systemctl status jellyfin

Windows

1. Download the Windows installer for your architecture.
2. Run it and choose whether to install Jellyfin as a background service or as a tray application.
3. When installation finishes, your browser opens to the setup wizard at http://localhost:8096.

Unraid

Add the community template repository under the Docker tab:

https://github.com/jellyfin/jellyfin/tree/master/deployment/unraid/docker-templates

Then click Add Container, select jellyfin, adjust the host paths for your config, cache, and media shares, and apply.

Portable binaries

Extract the archive and launch the server executable directly, supplying the data directory you want it to use:

./jellyfin --datadir /srv/jellyfin/data --ffmpeg /usr/bin/ffmpeg

Important

Jellyfin needs FFmpeg to transcode and to extract images, chapters, and subtitles. The Docker image and the native packages bundle a compatible jellyfin-ffmpeg build. If you run from portable binaries, install FFmpeg yourself and point to it with --ffmpeg (see Section 16).

3.3 Network ports

Jellyfin uses a small, fixed set of ports. The defaults come straight from the server's network configuration.

Tip

You only need 8096 open to use Jellyfin on your LAN. Open 8920 only if you set up HTTPS, and expose ports to the internet only after reading Section 8 and the Admin Guide's security chapter.

3.4 Verifying the server is up

Once started, confirm the server responds:

curl http://localhost:8096/System/Info/Public

{"LocalAddress":"http://192.168.1.50:8096","ServerName":"My Jellyfin",
 "Version":"12.0.0","ProductName":"Jellyfin Server","Id":"a1b2c3...",
 "StartupWizardCompleted":false}

StartupWizardCompleted is false until you finish the wizard in the next section. This public endpoint requires no login and is what client apps use to find and identify your server.

4. First-Time Setup Wizard

The very first time you open the web interface, Jellyfin runs a short setup wizard. Behind the scenes each step calls a /Startup/... endpoint, and the whole flow finishes by marking IsStartupWizardCompleted so the wizard never runs again.

Work through the steps in order:

1. Preferred display language. Sets the UI culture (the server default is en-US). You can change it later under Dashboard settings.

2. Create your first user. This account is automatically an administrator — it gets the IsAdministrator permission and full access to the Dashboard. Choose a strong password; password-less accounts are allowed but strongly discouraged for an admin.

   Caution

   The first user is your master account. If you forget its password, recovery requires server-side access (see Section 15, "I'm locked out"). Set a password you will not lose.

3. Set up your media libraries. You can add libraries now or skip and do it later. Each library needs a content type (Movies, Shows, Music, etc.) and one or more folders. See Section 6.

4. Preferred metadata language and country. Controls which language posters and descriptions are fetched in (defaults: language en, country US).

5. Configure remote access. Decide whether the server may be reached from outside your local network. This maps to the EnableRemoteAccess setting and can be changed anytime. Leave it off unless you have read Section 8.

6. Finish. The wizard completes and you land on the home screen.

Note

While the server is still booting — before the wizard is even available — Jellyfin runs a tiny temporary "setup" web server on the same port that shows live startup progress and any startup errors. If you load the page during boot and see a "still starting up" screen that auto-refreshes, that is expected.

5. A Tour of the Interface

After setup you arrive at the Home screen. The main areas you will use:

• Home — "Continue Watching", "Next Up", and "Recently Added" rows, plus a row per library. This is your launchpad.
• Library views — click a library (e.g. Movies) to browse, sort, and filter its contents.
• Item pages — click any movie, show, album, or person to see details, play, manage, or edit.
• Search — the magnifier searches across all your libraries.
• User menu (top-right avatar) — switch settings, log out, and reach the Dashboard (admins only).
• Dashboard — the administration area: server settings, users, libraries, plugins, scheduled tasks, logs, and live sessions. Most of the Dashboard is covered in the Admin Guide.

5.1 Casting and "Play On"

When you have more than one Jellyfin client or a Chromecast-style cast receiver available, an item's play menu lets you start playback on a different device and control it remotely. Remote control of another session requires the EnableRemoteControlOfOtherUsers (or shared-device-control) permission on your account.

6. Adding and Organizing Libraries

A library is a content type plus the folders that hold that content. Jellyfin scans those folders, identifies each item, and fetches metadata. Getting your folder and file names right is the single most important thing you can do — Jellyfin's matching accuracy depends on it.

6.1 Creating a library

1. Open Dashboard → Libraries (or use the wizard's library step).
2. Click Add Media Library.
3. Choose a Content type: Movies, Shows, Music, Music Videos, Photos, Books, Mixed Content, or others.
4. Give it a display name and add one or more folders.
5. Adjust the per-library options (metadata language, image fetchers, real-time monitoring, subtitle/trickplay extraction — see Section 6.5).
6. Save. Jellyfin immediately scans the new library.

6.2 Movie naming

Put each movie in its own folder named Title (Year), with the video file named the same way:

Movies/
├── The Matrix (1999)/
│   └── The Matrix (1999).mkv
├── Blade Runner (1982)/
│   ├── Blade Runner (1982).mkv
│   └── Blade Runner (1982)-trailer.mkv
└── Dune (2021)/
    └── Dune (2021) [2160p].mkv

Tip

The (Year) disambiguates remakes (e.g. Dune (1984) vs Dune (2021)). Anything in [square brackets] — resolution, codec, edition — is ignored for matching but can be parsed for technical display.

Multi-version and multi-part movies, extras (-trailer, -deleted, -behindthescenes suffixes and extras/ subfolders), and alternate cuts are all recognized by Jellyfin's naming engine.

6.3 TV show naming

Use a folder per series, a subfolder per season, and episode files tagged with SxxEyy:

Shows/
└── The Expanse (2015)/
    ├── Season 01/
    │   ├── The Expanse S01E01.mkv
    │   └── The Expanse S01E02.mkv
    └── Season 02/
        └── The Expanse S02E01-E02.mkv

Note

Jellyfin understands many episode patterns: S01E01, 1x01, date-based episodes for daily shows, episode ranges like S02E01-E02, and a "Specials" season (season 0). The display name for season 0 defaults to "Specials".

6.4 Music naming

Organize music by Artist/Album/Track:

Music/
└── Daft Punk/
    └── Discovery (2001)/
        ├── 01 - One More Time.flac
        └── 02 - Aerodynamic.flac

Embedded tags (artist, album, track number, cover art) are read directly from the files, so clean tags matter more than folder names for music.

6.5 Key per-library options

Each library has its own options. The ones you will touch most:

Tip

Turn Real-time monitoring on for libraries you add to frequently so new files appear without waiting for the next scheduled scan. There is a built-in delay (about 60 seconds by default) before a detected change triggers a scan, which prevents half-copied files from being imported.

6.6 Scanning and refreshing

Jellyfin scans automatically: on a schedule, when real-time monitoring fires, and when you click Scan All Libraries or Refresh Metadata on a library or item. A scan does three things — finds new/changed/removed files, identifies them, and fetches missing metadata and images.

Warning

"Replace all metadata" on a refresh will overwrite any manual edits you made with freshly downloaded data. Use "Search for missing metadata" instead when you only want to fill gaps.

7. Playing Your Media

Click any item and press Play. From the item page you can:

• Choose a specific version, audio track, and subtitle track before or during playback.
• Resume from where you left off — Jellyfin records your position and marks items watched once you pass a threshold (about 90% of the runtime by default).
• Mark items played/unplayed or favorite manually.

7.1 Subtitles

Jellyfin uses subtitles from three sources, in this order of convenience:

1. External sidecar files next to the media (e.g. The Matrix (1999).en.srt). Language and "forced"/"default" flags are parsed from the filename.
2. Embedded subtitles muxed into the container.
3. Downloaded subtitles from subtitle-provider plugins you enable per library.

Tip

Set an audio and subtitle language preference in your user settings and turn on "Remember subtitle selections" so Jellyfin auto-picks the right tracks every time instead of asking.

7.2 Why playback sometimes pauses to "transcode"

If your client can play a file's format directly, Jellyfin streams it untouched — Direct Play — using almost no server CPU. If the client cannot handle the container, codec, or bitrate, Jellyfin transcodes: it re-encodes the stream in real time into something the client supports. Transcoding is normal and powerful, but it uses real CPU/GPU. See Section 10 for how to make it fast.

8. Remote Access (Watching Away From Home)

By default Jellyfin is reachable only on your local network. To watch when you are away, you enable remote access — but do it carefully.

8.1 Turning remote access on

In Dashboard → Networking, the relevant settings include:

Caution

Exposing Jellyfin directly to the internet by forwarding port 8096 sends your traffic unencrypted. The recommended approach is a reverse proxy (nginx, Traefik, Caddy) that terminates HTTPS in front of Jellyfin. Automatic UPnP port-mapping is no longer supported and has been removed. Full reverse-proxy guidance is in the Admin Guide.

8.2 Finding your server automatically

On the LAN, client apps discover your server by broadcasting on UDP port 7359 ("who is JellyfinServer?"), and the server answers with its address, name, and ID. This is why most apps "just find" your server without you typing an address — as long as auto-discovery is enabled and the client is on the same network.

8.3 Quick Connect — log in without typing a password

Quick Connect lets you sign in on a TV or game console without entering your username and password on an awkward on-screen keyboard.

1. On the new device, choose Quick Connect. It shows a 6-digit code.
2. On a device where you are already logged in, open User menu → Quick Connect and enter that code.
3. The new device is signed in as you.

Note

Quick Connect codes are six digits and expire after 10 minutes. The feature must be enabled on the server (QuickConnectAvailable, on by default). Each code can only be authorized once.

9. Users, Profiles, and Parental Controls

Jellyfin supports many user accounts on one server, each with separate watch state, preferences, and a granular permission set. Manage them in Dashboard → Users.

9.1 What each user gets

• Their own Continue Watching, Next Up, favorites, and play history.
• Personal audio/subtitle language preferences and playback options like "auto-play next episode".
• An optional profile PIN (EnableLocalPassword) for quick on-device switching.

9.2 Permissions you can grant or revoke

Administrators control exactly what each account may do. The full permission set:

Tip

For a kids' account, leave IsAdministrator off, grant only the libraries you approve, and set a maximum parental rating so age-inappropriate items are hidden. You can also block specific tags.

9.3 Forgotten passwords

If a user forgets their password, an in-network password reset produces a short-lived PIN (valid 30 minutes) that, when redeemed, clears the password. This only works for requests originating inside your local network, by design.

10. Transcoding and Hardware Acceleration

Transcoding is what lets one file play on every device. By default it runs on the CPU, which works but is heavy for 4K or many simultaneous streams. Enabling hardware acceleration offloads the work to your GPU.

10.1 Enabling hardware acceleration

Go to Dashboard → Playback → Transcoding and pick a Hardware acceleration type that matches your hardware. Jellyfin supports, among others:

• Intel Quick Sync (QSV) and VA-API (Intel/AMD on Linux)
• NVIDIA NVENC/NVDEC
• AMD AMF
• Apple VideoToolbox

Note

On Linux with Intel/AMD, the VA-API render device defaults to /dev/dri/renderD128. If you run in Docker you must pass that device into the container. Hardware-encoding details and per-vendor setup live in the Admin Guide.

10.2 Settings worth knowing

These options shape transcoding quality and resource use:

Tip

If playback stutters or your server pegs at 100% CPU, the cause is almost always video transcoding without hardware acceleration. Enable HW accel, or encourage Direct Play by storing widely compatible files (H.264 MP4/MKV with AAC audio).

Warning

The transcode path can fill a disk quickly during heavy use. Put it on a fast drive with room to spare, and consider enabling segment deletion. If the transcode directory is unwritable, the server refuses to start — this is an intentional safety check.

11. Trickplay (Scrubbing Previews)

Trickplay generates the little preview thumbnails you see when you scrub the seek bar. Enable trickplay image extraction per library; Jellyfin then produces tiled preview images in the background.

Defaults that affect generation: one image roughly every 10 seconds, 320px-wide previews, tiles arranged 10×10, JPEG quality 90, running at below-normal process priority so it does not starve playback. Generation is non-blocking by default — your library stays usable while previews build.

Tip

Trickplay is one of the nicest quality-of-life features. The trade-off is disk space and one-time CPU/GPU work per file, so enable it on your most-watched libraries first.

12. Collections and Playlists

Collections group related items — a film franchise, a director's works, a themed set — into a single browsable entry. Create one from any item's menu (Add to Collection), or let Jellyfin build franchise collections automatically when a library option enables it. Managing collections requires the EnableCollectionManagement permission.

Playlists are ordered lists you build yourself, most commonly for music but usable for video too. They can be private to you or shared with other users.

Important

A known issue (#17022) can expose playlists belonging to other users in some situations. If you store sensitive playlists, keep your server updated and review playlist sharing. See the Admin Guide's security notes.

13. Live TV and DVR

If you have a TV tuner (for example an HDHomeRun network tuner) and a program guide source (such as an XMLTV file or a guide-listing provider), Jellyfin becomes a DVR.

1. Dashboard → Live TV → Add tuner, choose the tuner type, and enter its address.
2. Add a guide data source (XMLTV file or listings provider) and map channels to guide entries.
3. Browse the Guide, watch live channels, and schedule recordings — one-off or series.

Note

Watching Live TV requires the EnableLiveTvAccess permission; scheduling and managing recordings requires EnableLiveTvManagement. Recordings land in a folder you configure and appear like any other library item.

14. Plugins

Plugins extend Jellyfin — extra metadata providers, subtitle sources, themes, and integrations. Install them from Dashboard → Plugins → Catalog.

1. Open the Catalog, pick a plugin, and install it.
2. Restart the server when prompted.
3. Configure the plugin from its entry under My Plugins.

Bundled metadata/image providers you can enable per library include TheMovieDb (TMDb), The Open Movie Database (OMDb), MusicBrainz, TheAudioDb, ListenBrainz, Studio Images, and book providers like ComicVine, Google Books, and Open Library (ISBN).

Caution

Plugins run with full server access. Install only plugins you trust. You can add third-party plugin repositories, but treat unknown repositories with the same caution you would any software source.

15. Troubleshooting

Each entry gives the symptom, the likely cause, the fix, and how to avoid it.

Error: The server is expected to host the web client, but the provided content directory is either invalid or empty

• Cause: The web client files are missing from the expected web directory.
• Solution: Reinstall using a package or image that bundles the web client, or pass the correct path with --webdir. To run API-only with no web UI, start with --nowebclient.
• Prevention: Use the official Docker image or native packages, which include the web client.

Error: Kestrel failed to start! This is most likely due to an invalid address or port bind

• Cause: The configured bind address or port is wrong or already in use.
• Solution: Free port 8096 (or your configured port), or correct the bind interfaces in your network settings, then restart.
• Prevention: Don't run two servers on the same port; check for an existing Jellyfin instance before starting a new one.

Symptom: New files don't show up

• Cause: No scan has run since you added them, or the path isn't in a library.
• Solution: Run Scan All Libraries, confirm the folder is included in a library, and check file/folder naming.
• Prevention: Enable Real-time monitoring on libraries you add to often.

Symptom: Playback buffers, stutters, or server CPU spikes to 100%

• Cause: The client can't Direct Play the file, so the server is software transcoding video.
• Solution: Enable hardware acceleration, lower the client's quality setting, or store more compatible files (H.264 + AAC).
• Prevention: Standardize on widely supported formats; set up HW transcoding.

Symptom: The transcode folder fills my disk

• Cause: Heavy transcoding writes large temporary segment files.
• Solution: Move the transcode path to a roomy/fast disk and enable segment deletion. Run the Clean Transcode Directory scheduled task.
• Prevention: Reduce transcoding by encouraging Direct Play.
• Reference: Community issues #16912 and #16590 discuss transcode-cache retention behavior.

Symptom: A movie or episode matched the wrong title

• Cause: Ambiguous naming.
• Solution: Rename to Title (Year) / SxxEyy, then use Identify on the item to pick the correct match, and refresh.
• Prevention: Follow the naming conventions in Section 6.

Symptom: Episodes land in an "Unknown" season or get duplicated

• Cause: Episode files lack a recognizable SxxEyy pattern, or NFO/metadata conflicts (see issues #16381, #16989).
• Solution: Fix the episode filenames, remove conflicting NFO entries, and refresh metadata.
• Prevention: Keep one clean naming scheme across a series.

Symptom: The container starts very slowly

• Cause: Large libraries, slow storage, or first-run database setup (issue #13287).
• Solution: Use fast storage for /config, let the first scan complete, and run the Optimize Database scheduled task periodically.
• Prevention: Keep the config/database directory on an SSD.

Symptom: I'm locked out / forgot the admin password

• Cause: Lost admin credentials.
• Solution: Use the in-network password-reset PIN flow if available, or have a server administrator reset it server-side. (The mechanics are in the Admin Guide.)
• Prevention: Record the admin password somewhere safe; create a second admin account as a backup.

Tip

Your logs are the best diagnostic. Read them in Dashboard → Logs, or fetch them from the log directory. When asking for help, include the relevant log lines around the time of the problem.

16. Command-Line Reference

When you run the server binary directly (portable installs, custom services), the following options are available. They are parsed at startup.

Settings can also be supplied via environment variables prefixed with JELLYFIN_ (for example JELLYFIN_DATA_DIR).

./jellyfin --datadir /srv/jf/data --cachedir /srv/jf/cache --ffmpeg /usr/bin/ffmpeg

[INF] Jellyfin version: 12.0.0
[INF] Startup complete 0:00:07

Note

Under Docker or the native packages you rarely need these flags — the container/service sets sensible paths for you. They matter most for portable and custom deployments.

17. Default Locations Cheat-Sheet

Jellyfin keeps several distinct directories. Exact paths vary by platform and by the flags above, but the roles are constant:

Important

For backups, the config/data directory is what truly matters — it contains your database, users, and settings. Cache, transcodes, and trickplay can all be regenerated. The Admin Guide covers the built-in backup-and-restore feature.

18. Frequently Asked Questions

Q: Is Jellyfin really free? What's the catch? Yes. Jellyfin is free and open source with no paid tier, no account requirement, and no telemetry selling your data. The "catch" is that you host it yourself.

Q: Do I need an internet connection to use it? Only for downloading metadata and artwork, and for remote access. Local playback of your own files works fully offline.

Q: Can multiple people watch different things at once? Yes. The only limit is your server's ability to Direct Play or transcode the concurrent streams. Hardware acceleration dramatically raises that ceiling.

Q: What's the difference between Direct Play, Remux, and Transcode? Direct Play streams the file untouched (cheapest). Remux repackages the same audio/video into a different container without re-encoding (cheap). Transcode re-encodes the video and/or audio (expensive). Jellyfin picks the lightest option the client can handle.

Q: Why does my 4K movie transcode to a phone but Direct Play to my TV? Your TV supports the file's codec and your phone (or the network to it) does not, so Jellyfin transcodes only where necessary.

Q: How do I add a TV tuner / DVR? See Section 13. You need a supported tuner and a guide data source.

Q: Can I access my server from outside my house? Yes — enable remote access and, ideally, put a reverse proxy with HTTPS in front of it. See Section 8 and the Admin Guide. Do not blindly forward port 8096 to the internet.

Q: How do I log in on my TV without typing a password? Use Quick Connect (Section 8.3).

Q: Where are subtitles supposed to go? External subtitle files go next to the media with a language code (Movie (2020).en.srt). Embedded subtitles work automatically. You can also enable subtitle-provider plugins to download them.

Q: My posters are wrong / in the wrong language. How do I fix it? Use Identify to re-match the item, set the library's preferred metadata language, and refresh. Avoid "Replace all metadata" if you have manual edits.

Q: Does Jellyfin change or delete my media files? No, not during normal use. It only writes sidecar metadata/images if you enable "save with media", and it only deletes files if a user with the EnableContentDeletion permission explicitly does so.

Q: How do I keep my setup safe before exposing it online? Use strong admin passwords, give each person their own least-privilege account, keep the server updated, restrict CORS and remote IPs, and use HTTPS via a reverse proxy. The Admin Guide has a full hardening checklist.

Q: How many libraries/users can I have? There is no hard limit; practical limits are your storage and server CPU/RAM.

Q: Can I run Jellyfin behind a subpath like example.com/jellyfin? Yes — set a Base URL in the network settings.

Q: How do I update Jellyfin? Docker: pull a newer image tag and recreate the container. Native: update through your package manager or re-run the installer. Always back up /config first.

Q: A feature I want isn't here — can I extend it? Often yes, via plugins (Section 14) or the documented REST API (see the Admin Guide). Jellyfin is a platform, not just an app.