A personal media library can be a lovely home-server project: a few family videos, a music collection, and films you have the right to store and stream. Jellyfin adds a browsable interface so you can choose something from a television or phone instead of hunting through folders.

A Raspberry Pi is best treated as a modest direct-play experiment here. Jellyfin's hardware guidance warns against Raspberry Pi deployments because of transcoding limitations. If dependable multi-user streaming is the goal, choose a more capable server.

Set realistic expectations

Direct play sends a compatible file to a client without converting the video. Transcoding changes the format, resolution, or other properties during playback. Subtitles and audio compatibility can also trigger extra work, even when the video looks like it should be supported.

Use a Pi 4 or 5, 64-bit Raspberry Pi OS, Ethernet, and local SSD storage for this experiment. Install Docker Engine and the Compose plugin using the official Debian instructions linked below, selecting the supported 64-bit path for your OS. Verify sudo docker compose version before continuing.

Prepare a small library

Create a project folder and a media directory. Copy one short video you own into media before adding a large collection. Starting small makes library permissions and playback problems easier to separate.

BASH
mkdir -p "$HOME/jellyfin/media"
cd "$HOME/jellyfin"
nano compose.yaml

Save this as compose.yaml. Named volumes keep the configuration and cache separate from the container, while the media folder is mounted read-only.

YAML
services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    restart: unless-stopped
    ports:
      - "8096:8096"
    volumes:
      - jellyfin-config:/config
      - jellyfin-cache:/cache
      - ./media:/media:ro
volumes:
  jellyfin-config:
  jellyfin-cache:

The latest tag is convenient for the initial experiment, but it can change between deployments. Before treating this as a long-lived server, record a tested version and follow Jellyfin's upgrade notes. This minimal configuration leaves the image's default user unchanged; use the official guide to configure a non-root user with suitable volume permissions as you harden the setup.

BASH
sudo docker compose config
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=60 jellyfin

Open the library and test playback

Visit http://PI_ADDRESS:8096 from your LAN and complete the setup wizard. Add a library pointing at /media, which is the path inside the container. The host's home-directory path will not be visible there under the same name.

Play the sample on the actual television, phone, or browser you plan to use. Inspect the playback details to see whether it is direct playing or transcoding. Try seeking and enabling subtitles. A successful library scan says nothing about whether a particular client can decode the file efficiently.

Fix bottlenecks in a useful order

If the movie buffers, first check the playback mode. If it is transcoding, test a file already compatible with the client or prepare a compatible copy on a stronger computer. Then check network quality and disk performance. Increasing a buffer will not turn the Pi into a powerful transcoding server.

If the library is empty, check that the file exists in the host's media directory and that the container can read it. If the service does not start, inspect the logs for storage or port errors. Keep port 8096 private to your trusted network.

Keep the collection and configuration separate

Back up your original media independently of Jellyfin. The configuration volume contains a different kind of value: users, library settings, and server state. Stop the service before making a consistent backup of its data volume, and keep a written record of the container version.

For a household that mainly wants shared files, a Samba NAS may be enough. Jellyfin earns its place when its library interface improves the way you actually watch and listen.

Sources and further reading

About this guide

Researched from the official documentation linked above on September 10, 2026. Setup examples are starting points and have not been hardware-tested by Open Pi. Check your board, OS, and the project’s current instructions before installing.