# 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.

```bash
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
```

```text
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](#4-first-time-setup-wizard).

> [!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](#3-installation).

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.

```text
   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](#6-adding-and-organizing-libraries)).

---

## 3. Installation

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

### 3.1 Choosing an installation method

| Method | Best for | Updates |
|---|---|---|
| **Docker** | Most users, NAS, homelab | Pull a new image tag |
| **Native Linux packages** (`.deb`/`.rpm`) | Dedicated Linux box | System package manager |
| **Windows installer / tray app** | Windows desktop or server | Re-run installer |
| **macOS app** | Mac mini media servers | Replace the app |
| **Portable / binary archive** | Custom or unsupported OS | Replace the binaries |

### 3.2 Install steps

=== "Docker (compose)"

    Create a `docker-compose.yml`:

    ```yaml
    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:

    ```bash
    docker compose up -d
    ```

    ```text
    [+] Running 1/1
     ✔ Container jellyfin  Started
    ```

=== "Debian / Ubuntu"

    ```bash
    sudo apt update
    sudo apt install jellyfin
    ```

    ```text
    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`:

    ```bash
    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:

    ```text
    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:

    ```bash
    ./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](#16-command-line-reference)).

### 3.3 Network ports

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

| Port | Protocol | Purpose | Default |
|---|---|---|---|
| `8096` | TCP/HTTP | Web interface and API | Always on |
| `8920` | TCP/HTTPS | Encrypted web interface and API | Only if HTTPS is enabled |
| `7359` | UDP | Client auto-discovery on the LAN | On unless disabled |
| `1900` | UDP | DLNA / SSDP discovery | Only if DLNA is in use |

> [!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](#8-remote-access-watching-away-from-home) and the Admin Guide's
> security chapter.

### 3.4 Verifying the server is up

Once started, confirm the server responds:

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

```text
{"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](#15-troubleshooting), "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](#6-adding-and-organizing-libraries).

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](#8-remote-access-watching-away-from-home).

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](#65-key-per-library-options)).
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:

```text
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`:

```text
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`:

```text
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:

| Option | What it does | Default |
|---|---|---|
| Preferred metadata language | Language for fetched posters/descriptions | (server default) |
| Real-time monitoring | Auto-detect file changes without waiting for a scan | Off |
| Save artwork/metadata with media | Write `.nfo`/images next to files (portable) | Off |
| Extract chapter images | Generate thumbnails at chapter marks | Off |
| Extract trickplay images | Generate scrubbing previews (see [Section 11](#11-trickplay-scrubbing-previews)) | Off |
| Automatically merge series | Group split seasons across folders into one show | On |
| Allow embedded subtitles | Use subtitles muxed into the file (All / Text / Image / None) | Allow all |
| Automatically add to collection | Group franchise entries into a collection | Off |

> [!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](#10-transcoding-and-hardware-acceleration)
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:

| Setting | Meaning |
|---|---|
| Allow remote connections | Master switch for access outside the LAN (`EnableRemoteAccess`) |
| LAN networks | Which subnets count as "local" |
| Known proxies | Trusted reverse proxies for forwarded-header handling |
| Remote IP filter | An allow-list or block-list of remote addresses |
| Secure connection (HTTPS) | Enable TLS plus certificate path/password |
| Base URL | Serve Jellyfin under a path prefix (e.g. `/jellyfin`) |

> [!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:

| Permission | Grants the user… |
|---|---|
| `IsAdministrator` | Full Dashboard and server administration |
| `IsDisabled` | (When set) the account is blocked from logging in |
| `IsHidden` | Hide the account from login screens |
| `EnableMediaPlayback` | Play media at all |
| `EnableAudioPlaybackTranscoding` | Allow audio transcoding for this user |
| `EnableVideoPlaybackTranscoding` | Allow video transcoding for this user |
| `EnablePlaybackRemuxing` | Allow remuxing (repackaging without re-encoding) |
| `ForceRemoteSourceTranscoding` | Always transcode remote-source streams |
| `EnableContentDownloading` | Download items for offline playback |
| `EnableContentDeletion` | Delete media from libraries |
| `EnableMediaConversion` | Convert media to other formats |
| `EnableSyncTranscoding` | Transcode during sync/download |
| `EnableAllFolders` / per-folder | Access all libraries, or a chosen subset |
| `EnableAllChannels` | Access all channels |
| `EnableAllDevices` / per-device | Use any device, or only approved ones |
| `EnableRemoteAccess` | Connect from outside the LAN |
| `EnableLiveTvAccess` | Watch Live TV |
| `EnableLiveTvManagement` | Manage Live TV recordings and settings |
| `EnableCollectionManagement` | Create and edit collections |
| `EnableSubtitleManagement` | Download/manage subtitles |
| `EnableLyricManagement` | Manage lyrics |
| `EnableRemoteControlOfOtherUsers` | Control other users' sessions |
| `EnableSharedDeviceControl` | Control shared/cast devices |
| `EnablePublicSharing` | Share items publicly |

> [!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:

| Setting | Effect | Default |
|---|---|---|
| Enable hardware encoding | Use the GPU to *encode*, not just decode | On |
| Allow HEVC / AV1 encoding | Permit more efficient output codecs | Off |
| H.264 / H.265 quality (CRF) | Lower = better quality, bigger files (23 / 28) | 23 / 28 |
| Encoding thread count | CPU threads for software transcode (`-1` = auto) | Auto |
| Throttle transcodes | Pause encoding when the client buffer is full | Off |
| Delete old segments | Free disk by removing played HLS segments | Off |
| Tone mapping | Convert HDR to SDR for non-HDR screens | Off |
| Subtitle extraction | Pre-extract embedded subtitles for faster starts | On |
| Transcode path | Where temporary transcode files are written | `<cache>/transcodes` |

> [!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](#6-adding-and-organizing-libraries).

### 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.

| Option | Alias | Purpose |
|---|---|---|
| `--datadir` | `-d` | Data folder (database, etc.) |
| `--configdir` | `-c` | Configuration directory (settings, pictures) |
| `--cachedir` | `-C` | Cache directory |
| `--webdir` | `-w` | Web UI resources directory |
| `--logdir` | `-l` | Log file directory |
| `--ffmpeg` | | Path to an external FFmpeg executable |
| `--nowebclient` | | Run API-only; do not host the web client |
| `--service` | | Run as a headless service |
| `--package-name` | | Internal packaging identifier (e.g. synology) |
| `--published-server-url` | | URL to advertise via auto-discovery |
| `--nonetchange` | | Do not react to network status changes |
| `--restore-archive` | | Restore the server from a backup archive |
| `--mode` | | Action to perform on start (default: run as media server) |

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

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

```text
[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:

| Directory | Holds |
|---|---|
| Config | Your settings XML, the database, plugins, and plugin configs |
| Data | Program data and internal state |
| Cache | Image cache and other regenerable data |
| Transcodes | Temporary transcoding output (under cache by default) |
| Trickplay | Generated scrubbing preview images |
| Metadata | Downloaded posters, backdrops, and descriptions |
| Logs | Server log files |
| Backups | Backup archives created by the server |

> [!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](#13-live-tv-and-dvr). 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](#8-remote-access-watching-away-from-home) 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](#83-quick-connect--log-in-without-typing-a-password)).

**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](#14-plugins)) or the documented REST API
(see the Admin Guide). Jellyfin is a platform, not just an app.

---

_Generated June 2026 from jellyfin/jellyfin at 53c1c49. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._