Jellyfin Raspberry Pi 5: Complete Hardware Decode and Network Shares Setup Guide

Jellyfin Raspberry Pi 5 gives you a self-hosted media server with hardware-accelerated video decode, no subscription, and no data leaving your network. Jellyfin streams your movie and TV library to phones, browsers, smart TVs, and Kodi clients simultaneously. The Pi 5 handles HEVC and VP9 decode via the V4L2 M2M interface, keeping CPU load manageable during playback. Network shares from a NAS or another machine mount cleanly and appear to Jellyfin as local storage. This guide covers installation with the current APT keyring method, V4L2 hardware decode configuration, SMB and NFS share mounting, direct play optimisation, and troubleshooting.

Last tested: Raspberry Pi OS Bookworm Lite 64-bit | May 3, 2026 | Raspberry Pi 5 (8GB) | Jellyfin 10.9 | FFmpeg 6.x with V4L2 M2M

Key Takeaways

• The Pi 5 removed the dedicated H.264 hardware decoder present in Pi 4. HEVC (H.265) and VP9 decode well via V4L2 M2M. H.264 decodes via a software-assisted path that uses less CPU than pure software but is not equivalent to the Pi 4’s dedicated H.264 block. Recode existing H.264 libraries to HEVC for the best Pi 5 decode performance.
• Direct play is always preferable to transcoding on Pi hardware. Configure Jellyfin clients to request direct play and match the codec to what the client supports natively. Every transcoding stream costs CPU. On the Pi 5 a single 1080p transcode saturates one or two cores, leaving little headroom for other services.
• Mount network shares in /etc/fstab with the nofail and x-systemd.automount options. Without nofail, a NAS that is offline during boot will prevent the Pi from completing startup.

Jellyfin Raspberry Pi 5: How It Works

Jellyfin is a media server that scans a library directory, reads metadata from file names and embedded tags, fetches cover art and descriptions from TMDB and TheTVDB, and serves streams to clients over HTTP. Clients receive either a direct stream (the file as-is, decoded by the client device) or a transcoded stream (re-encoded on the fly by the Pi). Direct play is fast and CPU-free on the server side. Transcoding is CPU-intensive and should be minimised on Pi hardware.

Hardware decode offloads the decode portion of a transcode to the Pi 5’s VideoCore VII GPU via the V4L2 M2M (memory-to-memory) kernel interface. This applies when Jellyfin needs to transcode a stream (for example, a client that cannot decode HEVC natively). Hardware decode reduces CPU usage during transcoding but does not eliminate it, as the encode side (converting to H.264 for the client) still runs on CPU.

Hardware Preparation

The Pi 5 with 4GB RAM handles Jellyfin with a small library and mostly direct play. The 8GB model is better for larger libraries, multiple simultaneous streams, or running Jellyfin alongside other services. Active cooling is required. Jellyfin scans, thumbnail generation, and transcoding sustain CPU load for extended periods. Without active cooling the Pi 5 thermally throttles above 80 degrees C, causing stuttering in streams. See Raspberry Pi 5 Cooling Guide for tested configurations.

Use the official 27W USB-C power supply. See Raspberry Pi Power Monitoring via USB for verification. Store the Jellyfin library and media on an SSD rather than microSD. See Booting Raspberry Pi from USB SSD for the setup.

Installing Jellyfin

Flash Raspberry Pi OS Bookworm Lite 64-bit using Raspberry Pi Imager. After first boot:

sudo apt update && sudo apt full-upgrade -y

Add the Jellyfin APT repository using the current keyring method:

curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key   | sudo gpg --dearmor -o /etc/apt/keyrings/jellyfin.gpg

echo "deb [signed-by=/etc/apt/keyrings/jellyfin.gpg] https://repo.jellyfin.org/debian bookworm main"   | sudo tee /etc/apt/sources.list.d/jellyfin.list

sudo apt update && sudo apt install jellyfin -y

sudo systemctl enable --now jellyfin
sudo systemctl status jellyfin

Expected result: systemctl status jellyfin shows the service active. Navigate to http://<pi-ip>:8096 and the Jellyfin onboarding wizard loads. Work through the wizard to create the admin account and set your library paths. If you have not mounted network shares yet, skip library setup and return after the next section.

V4L2 Hardware Decode Configuration

Confirm the V4L2 M2M devices are visible:

ls /dev/video*
# Expect: /dev/video10  /dev/video11  /dev/video12  etc.

v4l2-ctl --list-formats-ext --device /dev/video10

The V4L2 devices expose the codecs available for hardware decode. HEVC and VP9 appear as compressed capture formats on Pi 5. If /dev/video10 is not present, confirm you are running the 64-bit kernel:

uname -m
# Should return: aarch64

Confirm the Jellyfin FFmpeg build supports V4L2:

ffmpeg -hwaccels 2>/dev/null | grep v4l2

Expected result: v4l2m2m appears in the output. If it does not, update Jellyfin and the system packages. The Jellyfin-bundled FFmpeg build includes V4L2 support on Bookworm aarch64.

Enable hardware acceleration in the Jellyfin web interface. Go to Dashboard > Administration > Playback > Transcoding:

• Hardware acceleration: V4L2
• Enable hardware decoding for HEVC, VP8, VP9
• Thread count: 0 (auto)
• Encoding preset: medium or fast (slower presets use more CPU)

Grant the jellyfin user access to the V4L2 devices:

sudo usermod -aG video jellyfin
sudo systemctl restart jellyfin

Test hardware decode with a sample HEVC file:

ffmpeg -hwaccel v4l2m2m -c:v hevc_v4l2m2m -i /path/to/sample.mkv -f null - 2>&1 | grep -i "v4l2\|decoded\|frame"

Expected result: CPU usage stays significantly lower than a software decode of the same file. The output references V4L2 device opens and decoded frame counts.

Mounting Network Shares

Network shares let Jellyfin access media on a NAS or another machine without storing it locally. Both SMB (Samba) and NFS work well. NFS is generally faster on Linux-to-Linux setups and has less overhead. SMB is more compatible with Windows and most NAS devices.

SMB (Samba) shares

sudo apt install cifs-utils -y
sudo mkdir -p /mnt/media

Create a credentials file. Using a file keeps passwords out of /etc/fstab where they would be world-readable:

sudo tee /etc/samba/credentials <<EOF
username=your-nas-username
password=your-nas-password
EOF
sudo chmod 600 /etc/samba/credentials

Add to /etc/fstab:

//192.168.1.50/Media /mnt/media cifs credentials=/etc/samba/credentials,iocharset=utf8,uid=jellyfin,gid=jellyfin,vers=3.0,nofail,x-systemd.automount 0 0

sudo mount -a
ls /mnt/media

Expected result: The media directory contents are visible. If you see a “mount error(13): Permission denied,” the NAS share permissions do not allow access with the provided credentials. Check the NAS share access settings and confirm the username matches exactly.

NFS shares

sudo apt install nfs-common -y
sudo mkdir -p /mnt/media

Add to /etc/fstab:

192.168.1.10:/volume1/Media /mnt/media nfs defaults,nofail,x-systemd.automount,timeo=30 0 0

sudo mount -a
df -h /mnt/media

Expected result: df -h shows the NFS share mounted with the remote filesystem size and available space. For more on setting up NAS with Samba, see Time Machine Raspberry Pi NAS Samba.

Permissions for Jellyfin

Jellyfin runs as the jellyfin user. For SMB shares, the uid=jellyfin,gid=jellyfin mount options handle this. For NFS shares, confirm the files are readable by the jellyfin user:

# Check jellyfin user can read the mounted media
sudo -u jellyfin ls /mnt/media

# If permission denied, add jellyfin to the group that owns the files
sudo usermod -aG <owning-group> jellyfin
sudo systemctl restart jellyfin

Library Organisation and Direct Play

Jellyfin matches file names to metadata from TMDB and TheTVDB. The expected naming formats:

• Movies: Movie Title (Year)/Movie Title (Year).mkv
• TV shows: Show Name/Season 01/Show Name - S01E01.mkv

Each movie in its own directory, TV episodes organised by season. Files named differently will either not match metadata or match the wrong title.

Direct play is the priority for Pi 5 performance. In the Jellyfin mobile and web clients, check the media info for a playing item. It should show “Direct Play” rather than “Transcoding.” If it shows transcoding, the client does not support the container or codec. The most common cause is MKV containers that some clients cannot handle natively. Re-mux to MP4 using ffmpeg without re-encoding:

# Re-mux MKV to MP4 (no re-encode, very fast)
ffmpeg -i "input.mkv" -c copy "output.mp4"

For subtitle handling, external SRT files trigger direct play. Image-based subtitles (PGS, VOBSUB) force transcoding on most clients. Convert problematic subtitle tracks with:

ffmpeg -i "input.mkv" -map 0:s:0 "subtitle.srt"

Remote Access

Two practical options for accessing Jellyfin away from home:

• Tailscale: Install on both the Pi and your remote device. Access Jellyfin at http://<pi-tailnet-ip>:8096 without any port forwarding. See Tailscale Raspberry Pi.
• Caddy reverse proxy: Expose Jellyfin behind HTTPS on a domain with automatic Let’s Encrypt certificates. See Caddy Reverse Proxy Raspberry Pi. The Caddyfile entry: jellyfin.yourdomain.com { reverse_proxy localhost:8096 }

If exposing Jellyfin publicly via Caddy, enable the UFW firewall:

sudo apt install ufw -y
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Troubleshooting

Streams stutter or buffer

# Check CPU and temperature
htop
vcgencmd measure_temp

# Check if the stream is transcoding (should be direct play)
# Open Jellyfin web UI > click playing item > Media Info

Stuttering during transcoding is most often thermal throttling. If vcgencmd measure_temp returns above 80 degrees C, improve cooling before attempting other fixes. Stuttering during direct play on a wired connection points to a storage throughput problem. Check the SSD or NAS connection with hdparm -t /dev/sda.

Hardware decode not working

# Check jellyfin user is in the video group
groups jellyfin

# Check V4L2 devices exist
ls -la /dev/video*

# Check Jellyfin log for decode errors
journalctl -u jellyfin -n 50 | grep -i "v4l2\|decode\|error"

The two most common causes of hardware decode failure are the jellyfin user not being in the video group (fixed with sudo usermod -aG video jellyfin and a service restart) and the V4L2 hardware acceleration not being enabled in the Jellyfin dashboard settings.

Network share not mounting at boot

sudo systemctl daemon-reload
sudo mount -a
journalctl -b | grep -i "mount\|cifs\|nfs"

If the share fails to mount at boot but mounts manually, confirm nofail is in the fstab options so the Pi boots even when the NAS is offline. The x-systemd.automount option defers the mount until something first accesses the path, which avoids race conditions with network availability at boot.

Library not scanning or metadata wrong

# Trigger manual library scan
# Jellyfin web UI > Administration > Libraries > Scan All Libraries

# Check file naming
ls /mnt/media/Movies/
# Should be: Movie Title (Year)/Movie Title (Year).mkv

# Check jellyfin can read the files
sudo -u jellyfin ls /mnt/media/Movies/

Wrong metadata almost always means wrong file naming. Check the actual file and folder names against the expected format. Jellyfin provides a “Identify” option per item in the web UI to manually match a file to a specific TMDB or TheTVDB entry when automatic matching fails.

FAQ

Does Jellyfin support 4K on Raspberry Pi 5?

Yes, with HEVC (H.265) content and direct play enabled on a client that supports HEVC. The Pi 5 decodes HEVC via V4L2 M2M, which handles 4K streams without saturating the CPU. Direct play sends the stream as-is to the client. 4K transcoding on Pi 5 is not practical. It overwhelms the CPU regardless of hardware decode assistance.

What happened to H.264 hardware decode on Pi 5?

The Pi 5 removed the dedicated H.264 hardware decoder block present in Pi 4. H.264 decode on Pi 5 falls back to a software-assisted path via the CPU. In practice this means H.264 streams direct play fine on clients (no Pi involvement), but H.264 transcoding on the Pi 5 is CPU-heavy. For libraries with a large H.264 collection, converting to HEVC with ffmpeg improves the Pi 5 transcoding performance significantly.

Can I use Jellyfin and Plex on the same Pi?

Technically yes, but it is not recommended. Both services want to own the media scanning and transcoding pipeline, both use significant RAM, and they compete for V4L2 decode resources during concurrent streams. Run one or the other. Jellyfin is the better choice for self-hosted use. It has no features behind a paywall and no account requirement.

Is NFS or SMB better for Jellyfin on Pi?

NFS is faster on Linux-to-Linux connections and has lower overhead for sequential reads. SMB is more compatible with Windows NAS devices and supports more authentication options. For a Synology or QNAP NAS serving Linux clients, NFS is the better choice. For a Windows machine sharing media, SMB is the practical option. Both work reliably for Jellyfin streaming at 1080p and 4K bitrates over Gigabit Ethernet.

How many simultaneous streams can Pi 5 handle?

For direct play (no transcoding), the Pi 5 handles as many simultaneous streams as your network bandwidth allows. The Pi is serving files, not processing them. For transcoding, each simultaneous stream uses one to two CPU cores depending on resolution and codec. Two simultaneous 1080p HEVC transcodes is the practical limit before quality or stability degrades. Direct play is always the goal.

References

• https://jellyfin.org/docs/general/installation/linux/
• https://jellyfin.org/docs/general/post-install/transcoding/hardware-acceleration/
• https://jellyfin.org/docs/general/administration/storage/
• https://forum.jellyfin.org/t-raspberry-pi-for-hosting

---

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 5 (8GB), USB 3.0 SSD. Last tested OS: Raspberry Pi OS Bookworm Lite 64-bit. Jellyfin 10.9, FFmpeg 6.x with V4L2 M2M support.