Install Jellyfin on Raspberry Pi: Your Private Media Server

Commercial streaming services fragment your favorite movies, TV shows, and personal video libraries across multiple subscription tiers with ever-changing licensing agreements. Jellyfin is the 100% free, open-source media streaming system that puts you in complete ownership of your entertainment. With no licensing fees, no premium paywalls, and no tracking telemetry, Jellyfin delivers an experience as rich as Netflix or Plex.

Running Jellyfin on a Raspberry Pi allows you to stream movies, music, and shows to smart TVs (Roku, Apple TV, Android TV, Fire TV), gaming consoles, web browsers, and mobile phones across your local network and beyond.

This guide covers hardware planning, understanding video transcoding constraints on ARM processors, deploying Jellyfin via Docker Compose, attaching external media storage, configuring hardware acceleration where available, and optimizing client playback for Direct Play.

Hardware planning and video playback architecture

Understanding how media streaming works on low-power ARM computers is essential for setting realistic expectations and achieving smooth playback:

Direct Play vs Transcoding

• Direct Play (Recommended): When your playback device (such as an Apple TV, Nvidia Shield, or modern phone) natively supports the video and audio codecs of your file (such as H.264/HEVC video with AAC audio), the Raspberry Pi merely streams the raw data over the network. In Direct Play mode, CPU usage is under 5%, and a Raspberry Pi 4 or 5 can comfortably stream multiple concurrent 4K high-bitrate video streams without breaking a sweat!
• Transcoding (CPU/GPU Intensive): When a client device cannot decode a video format (for example, attempting to play high-bitrate AV1, VC-1, or incompatible PGS subtitle formats on an older browser), Jellyfin must decode the video and re-encode it in real time. The Raspberry Pi has a compact mobile processor; heavy real-time software transcoding of 4K HDR media will peg all CPU cores to 100% and cause video buffering.

Recommended Hardware:

• Raspberry Pi 5 or Raspberry Pi 4 with 4 GB or 8 GB of RAM. A 64-bit operating system is required.
• Gigabit Ethernet Connection: High-bitrate 4K Remuxes require 50–100+ Mbps of steady network throughput. A wired Ethernet connection eliminates Wi-Fi buffering.
• External Storage: USB 3.0 SSD or external powered hard drive formatted with ext4 to store your media library.

Mount your external media drive

Organize your media drive with standard naming conventions so Jellyfin's automated scrapers can retrieve metadata, cast lists, and poster artwork:

/mnt/media/
  movies/
    Inception (2010)/
      Inception (2010).mp4
  tv/
    Severance/
      Season 01/
        Severance - S01E01.mkv

Ensure your storage drive is mounted permanently via /etc/fstab and readable by your container:

sudo mkdir -p /mnt/media
sudo chown -R "$USER:$USER" /mnt/media
sudo chmod -R 755 /mnt/media

Deploy Jellyfin with Docker Compose

Deploying Jellyfin via Docker Compose isolates its dependencies and simplifies image updates.

Create a dedicated directory structure for Jellyfin:

mkdir -p "$HOME/jellyfin/config" "$HOME/jellyfin/cache"
cd "$HOME/jellyfin"

Create a compose.yaml file:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    restart: unless-stopped
    ports:
      - "8096:8096/tcp"
    environment:
      - TZ=UTC
      - JELLYFIN_PublishedServerUrl=http://192.168.1.50:8096
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /mnt/media:/media:ro
    devices:
      - /dev/dri:/dev/dri # GPU acceleration interface

Notice that /mnt/media is mounted with :ro (read-only). This protects your media files from accidental deletion by the web server. Replace 192.168.1.50 with your Raspberry Pi's actual local IP address, and set TZ to your local timezone.

Launch the container:

docker compose up -d
docker compose logs -f

Open http://<YOUR_PI_IP>:8096 in your browser to begin initial setup.

Initial onboarding and library configuration

When you open port 8096 for the first time, Jellyfin guides you through the setup wizard:

1. Preferred Language: Choose your primary metadata language.
2. Administrator Account: Create a username and strong password.
3. Add Media Libraries:
4. Click Add Media Library.
5. Select Content Type: Movies.
6. Enter Display Name: Movies.
7. Click the + button next to Folders, and select /media/movies.
8. Repeat for TV Shows (pointing to /media/tv).
9. Metadata Scrapers: Enable TheMovieDatabase (TMDb) and TheTVDB for automatic artwork, plot summaries, and episode ratings download.
10. Remote Access: Keep remote access enabled, but do not expose port 8096 to the public internet directly. Use Tailscale or Nginx Proxy Manager for secure remote streaming.

Tuning Playback and Hardware Acceleration

Navigate to Dashboard -> Playback -> Transcoding:

• Hardware Acceleration: On Raspberry Pi OS (Debian Bookworm), hardware decoding uses the Video4Linux2 (V4L2) driver. Set Hardware Acceleration to V4L2 or None. Because the Pi 5 utilizes a software-driven HEVC decode pipeline, high-efficiency software decoding combined with Direct Play client settings is often the most reliable strategy.
• Client Playback Settings (Direct Play First): On smart TVs, mobile apps, and media players:
• In client app settings, set Home Streaming Quality to Maximum (Original Quality). This forces the player to Direct Play the file without asking the Raspberry Pi to transcode.
• Choose subtitle formats that are supported natively (like SRT text subtitles). Avoid image-based bitmap subtitles (like PGS/VOBSUB), which require the server to "burn" the subtitles into the video frames using CPU transcoding.

Client applications and ecosystem

Jellyfin has native client applications for virtually every platform: - Smart TVs: Official apps for Roku, Apple TV (Swiftfin), Android TV, Fire TV, and LG webOS. - Mobile: Native apps for iOS and Android with offline download capabilities. - Kodi: The Jellyfin for Kodi plugin connects your Raspberry Pi library to high-end home theater PC setups. - Music Players: Connect apps like Finamp or Feishin to stream your self-hosted lossless music library.

Monitor Jellyfin with Open Pi

Streaming video places unique demands on network bandwidth and storage I/O.

With Open Pi on iOS and Android: - CPU & Thermal Status: Verify that video streaming does not spike CPU temperatures into thermal throttling. - Network Bandwidth: Monitor real-time upload megabits per second when family members are streaming movies. - Container Uptime: Check container resource utilization and view logs directly from your mobile device.

Troubleshooting Jellyfin playback issues

• Playback Stutters or Buffers Frequently: Check the Jellyfin dashboard during playback. If the stream info shows Transcoding instead of Direct Play, identify the reason (e.g., "Audio codec not supported" or "Bitrate exceeds limit"). Convert media to H.264/AAC MP4 or upgrade the client application settings to Maximum quality.
• Libraries Missing Posters or Artwork: Ensure the Raspberry Pi has internet access to reach themoviedb.org. Check folder permissions; Jellyfin needs permission to read directory contents.
• 500 Internal Server Error: Verify that the external media drive did not unmount. Run df -h /mnt/media to ensure the storage path is still mounted and accessible.

Sources and further reading

• Jellyfin: Official Documentation and Server Setup
• Jellyfin: Hardware Acceleration Setup and Drivers
• Jellyfin: Media Preparation and File Naming Guidelines

Monitor your Raspberry Pi from your phone

Check real-time CPU, RAM, temperature, and service health for your home server projects with Open Pi for iOS and Android. Local-first, private, and no cloud account required.

Explore Open Pi ↗App StoreGoogle Play