Jellyfin: The Free Self-Hosted Media Server for Your Homelab

Plex costs $120/year for a PlexPass subscription to unlock features that should be free. Emby charges $99 for a lifetime Premiere license. Jellyfin is 100% free, open source, and has no premium tier — all features are available to everyone.

Photo by Ajin K S on Unsplash

Here's how to set up Jellyfin in your homelab.

What Jellyfin Does

Jellyfin is a media server that:

• Organizes your movies, TV shows, music, photos, and books
• Streams to browsers, smart TVs, phones, and streaming devices
• Transcodes media on-the-fly for devices that can't play certain formats
• Fetches metadata (posters, descriptions, ratings) automatically
• Supports Live TV and DVR with a compatible tuner
• Handles multiple users with separate watch history and parental controls

It runs on your hardware, streams to anywhere you can reach it, and owns no part of your data.

Hardware Requirements

Jellyfin's requirements depend heavily on transcoding:

Direct stream (no transcoding):

• Minimal CPU — a Raspberry Pi 4 can handle multiple simultaneous streams
• Your network must deliver the bitrate (1080p remux = 40-80 Mbps)

Software transcoding (CPU):

• 2GHz+ multi-core CPU
• 1 core per simultaneous 1080p transcode, roughly
• 4GB+ RAM

Hardware transcoding (GPU/iGPU):

• Intel Quick Sync (most modern Intel CPUs with integrated graphics)
• NVIDIA NVENC (GTX 1050+)
• AMD VCE/AMF
• Hardware transcoding dramatically reduces CPU load

For a household with 1-3 users and modern devices capable of direct play, even a low-power N100/N150 mini PC works well.

Installing Jellyfin with Docker

The recommended method for homelab use:

# docker-compose.yml
services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    network_mode: host
    volumes:
      - /path/to/config:/config
      - /path/to/cache:/cache
      - /path/to/media:/media:ro
    restart: unless-stopped
    environment:
      - JELLYFIN_PublishedServerUrl=https://jellyfin.yourdomain.com

Volume mappings:

• /config — Jellyfin's configuration and database (back this up)
• /cache — Transcoding cache and thumbnails (can be regenerated)
• /media — Your media files (read-only recommended)

Start it:

docker compose up -d

Access at http://your-server:8096.

First-Time Setup

The setup wizard walks you through:

1. Create an admin account
2. Add media libraries — point Jellyfin to your movies and TV folders
3. Choose metadata providers — TheMovieDB and TheTVDB are the standards
4. Set your preferred language

Jellyfin scans your media and downloads metadata automatically. For best results, name your files using a consistent format:

Movies: Movie Title (Year)/Movie Title (Year).mkv

/media/movies/
  Blade Runner 2049 (2017)/
    Blade Runner 2049 (2017).mkv
  Inception (2010)/
    Inception (2010).mkv

TV Shows: Show Name/Season XX/Show Name - SXXEXX.mkv

/media/tv/
  Breaking Bad/
    Season 01/
      Breaking Bad - S01E01.mkv

Proper naming allows Jellyfin to match your files to the correct metadata 99% of the time.

Hardware Transcoding Setup

Hardware transcoding is essential for a smooth multi-user experience. For Intel Quick Sync:

For Docker, pass through the Intel GPU device:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    devices:
      - /dev/dri:/dev/dri
    group_add:
      - "109"  # render group (check your system: ls -la /dev/dri)

In Jellyfin settings:

1. Admin → Dashboard → Playback → Transcoding
2. Enable "Hardware acceleration"
3. Select your hardware encoder (Intel QSV, NVENC, etc.)
4. Enable hardware encoding for H.264, HEVC, etc.

Verify it's working: During a stream that requires transcoding, check Admin → Dashboard → Playback → check if "HW" appears next to the transcode.

Client Apps

Jellyfin has official clients for:

• Web browser — Works in all modern browsers, no install needed
• Android/iOS — Official Jellyfin apps (free, no subscription)
• Android TV/Fire TV — Official app
• Apple TV — Official app
• Kodi — Jellyfin for Kodi addon integrates Jellyfin into Kodi
• Roku — Community-maintained app

Third-party clients worth knowing:

• Infuse (iOS/tvOS) — Premium UI, handles almost any media format natively
• Swiftfin (iOS) — Open-source native iOS client

Reverse Proxy for Remote Access

For streaming outside your home network:

Nginx configuration:

server {
    listen 443 ssl;
    server_name jellyfin.yourdomain.com;

    location / {
        proxy_pass http://localhost:8096;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Large file support
        client_max_body_size 100m;
    }
}

Important: Set proxy_read_timeout to a long value (3600+) to prevent stream interruption on slow connections.

Multi-User Setup

Jellyfin handles multiple users well:

User types:

• Administrator — full access
• Standard user — access to libraries you grant
• Limited user — extra restrictions (kids accounts)

Per-user controls:

• Library access (hide adult content from kids' profiles)
• Remote access on/off
• Download permission
• Maximum bitrate limits
• Parental rating restrictions

Create accounts via Admin → Dashboard → Users.

Live TV and DVR

With a TV tuner (HDHomeRun network tuner or USB tuner), Jellyfin can:

• Stream live TV channels
• Schedule recordings (DVR)
• Set up guide data via XMLTV or EPG providers

This makes Jellyfin a full cable TV replacement for over-the-air channels.

Jellyfin vs. Plex: Key Differences

Plex's advantage is its relay (connecting remotely when direct connection fails) and its polish. Jellyfin wins on cost and privacy.

Common Issues and Fixes

Subtitle issues: Install FFmpeg properly and configure it in Jellyfin's transcoding settings.

Library scan not picking up new files: Manually trigger a library scan, or enable automatic scan on file change (requires inotify monitoring).

4K streaming buffering: 4K HDR requires either direct play (client supports H.265 + HDR) or powerful hardware transcoding. Software transcoding 4K is CPU-intensive.

Permission issues with media folder: Ensure the Jellyfin container user (UID 1000 by default) has read access to your media directory.

Backup Strategy

Back up /config regularly — this contains your database, user accounts, watch history, and metadata. The media files themselves are replaceable; the Jellyfin config is not.

A nightly backup of /config to a second location takes seconds and protects everything important.