/* raspi.dev */

How to Set Up Jellyfin Media Server on Raspberry Pi with Docker

Tom
Tom
#jellyfin#media#docker#pi#setup

How to Set Up Jellyfin Media Server on Raspberry Pi with Docker

Jellyfin is a free, open-source media server that lets you stream your personal media collection to any device on your network. It supports movies, TV shows, music, and photos with a polished web interface and apps for most platforms. Running it on a Raspberry Pi with Docker makes deployment and updates straightforward.

Prerequisites: You need Docker and Docker Compose installed on your Raspberry Pi. If you haven't set that up yet, see our Docker setup guide.

Prerequisites

  • Raspberry Pi 4 or 5 (4 GB RAM recommended)
  • Docker and Docker Compose installed
  • An external drive or USB storage with your media files
  • A stable network connection (Ethernet recommended for streaming)

Step 1: Create the Directory Structure

Set up the folders Jellyfin needs for configuration, cache, and media:

Bash
mkdir -p ~/jellyfin/config
mkdir -p ~/jellyfin/cache

Your media files can live on an external drive. For this guide, we will assume your media is stored at /mnt/media. Adjust the path to match your setup:

Bash
sudo mkdir -p /mnt/media/movies
sudo mkdir -p /mnt/media/tvshows
sudo mkdir -p /mnt/media/music

Step 2: Create the Docker Compose File

Create a docker-compose.yml file in the Jellyfin directory:

Bash
nano ~/jellyfin/docker-compose.yml

Paste the following configuration:

YAML
services:
  jellyfin:
    image: jellyfin/jellyfin
    container_name: jellyfin
    restart: unless-stopped
    ports:
      - "8096:8096"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /mnt/media:/media:ro
    environment:
      - TZ=America/New_York
    devices:
      - /dev/video10:/dev/video10
      - /dev/video11:/dev/video11
      - /dev/video12:/dev/video12
    group_add:
      - "video"

The devices entries pass the V4L2 hardware encoder/decoder for transcoding. The media volume is mounted read-only so Jellyfin cannot modify your files.

Step 3: Start Jellyfin

Start the container and verify it is running:

Bash
cd ~/jellyfin
docker compose up -d
docker ps

Step 4: Run the Initial Setup Wizard

Open a browser and navigate to:

Code
http://<your-pi-ip>:8096

The setup wizard will walk you through selecting a language, creating an admin account, adding media libraries, and configuring remote access.

Step 5: Add Media Libraries

After completing the wizard, add your media libraries:

  1. Go to Dashboard > Libraries (or Administration > Libraries)
  2. Click Add Media Library
  3. For a movie library:
    • Content type: Movies
    • Folders: Click the + button and enter /media/movies
    • Leave metadata settings at their defaults
  4. Click OK and repeat for TV Shows (/media/tvshows) and Music (/media/music)

Jellyfin will scan each library and automatically download metadata, artwork, and subtitles.

Step 6: Enable Hardware Transcoding with V4L2

The Raspberry Pi 4 includes a hardware video encoder/decoder accessible through V4L2. To enable it:

  1. Go to Dashboard > Playback > Transcoding
  2. Set Hardware acceleration to Video4Linux2 (V4L2)
  3. Click Save

This offloads video transcoding from the CPU to the dedicated hardware block, significantly reducing CPU load during playback. Note that V4L2 on the Pi 4 supports H.264 encoding and decoding. H.265/HEVC decoding is supported but encoding is not.

Note for Raspberry Pi 5 users: The Pi 5 removed the hardware video encoder. V4L2 hardware decoding still works, but transcoding will fall back to software encoding, which the Pi 5's faster CPU handles reasonably well.

Updating Jellyfin

To update to the latest version, pull the new image and recreate the container:

Bash
cd ~/jellyfin
docker compose pull
docker compose up -d

Your configuration and libraries are preserved in the mounted volumes.

Troubleshooting

  • Web UI not loading: Verify the container is running with docker ps. Check logs with docker logs jellyfin for errors.
  • Media not appearing: Ensure the file paths inside the container match what you configured in the library settings. Check that the media files have read permissions.
  • V4L2 devices not found: Verify the devices exist on the host with ls /dev/video*. If they are missing, ensure your Pi's firmware is up to date with sudo rpi-update.
  • Buffering during playback: Switch to a wired Ethernet connection. Lower the streaming quality in the client app settings. Enable hardware transcoding to reduce CPU load.
  • High CPU usage during transcoding: Confirm V4L2 hardware acceleration is enabled in the transcoding settings. If the source file is HEVC, the Pi 4's encoder can only output H.264.
  • Container won't start after reboot: Ensure Docker is enabled to start on boot: sudo systemctl enable docker.
  • Permission errors on config directory: Run sudo chown -R 1000:1000 ~/jellyfin/config ~/jellyfin/cache to fix ownership.

Conclusion

You now have a fully functional Jellyfin media server running on your Raspberry Pi. With hardware transcoding enabled and your media libraries configured, you can stream content to any device on your network. For automated media management, check out how to set up Sonarr and Radarr to automatically download and organize your TV shows and movies.