The first time I installed Jellyfin on TrueNAS Scale, it went live in about four minutes and then refused to see a single movie file. The container was running. The web page loaded. And the library scan found nothing, because I had done the one thing everyone does on their first try: I pointed it at a path inside the container that had no connection to my actual media.
That afternoon of head-scratching is exactly why this guide exists.
Jellyfin is a free, self-hosted media server, and it pairs beautifully with a NAS full of movies and shows. TrueNAS Scale runs apps in containers under the hood, so you get isolation and easy updates without touching a command line. The trick is understanding two things: how datasets map into the container, and how to hand the container your GPU so it can transcode without melting your CPU. Get those right and the rest is easy.
Before you touch the apps page
You need a dedicated dataset for your media and, ideally, one for Jellyfin's config. I keep mine as tank/media and tank/apps/jellyfin. Splitting config from media means you can nuke and reinstall the app without losing your watch history, users, or metadata.
Create these under Datasets in the TrueNAS web UI before you do anything else. A dataset is not the same as a plain folder; it is a ZFS filesystem with its own snapshots and permissions, which matters later.
Permissions are the quiet killer here. TrueNAS apps run as a specific user and group, and by default modern versions use the apps user with UID 568. If that user cannot read your media dataset, scans come back empty and you get no obvious error.
So set the media dataset ownership to allow read access for group 568, or open it up with a permissive ACL if this is a home box behind your own firewall. I usually give the apps group read and execute on media, and full control on the config dataset.
Installing the Jellyfin app
Head to Apps in the TrueNAS Scale sidebar, then Discover Apps, and search for Jellyfin. The official catalog entry is maintained by iXsystems and wraps the upstream container, so you are not hunting for a random image.
Click Install and you land on a configuration form. Do not rush through it. The fields that matter are the storage mounts and, if your hardware supports it, the GPU section.
- Application Name: leave it as jellyfin or name it something you will recognize.
- Config Storage: choose host path and point it at tank/apps/jellyfin. This holds the database and settings.
- Additional Storage: add a host path mount for your media. Set the host path to tank/media and the mount path inside the container to /media. Mark it read-only if you never want Jellyfin writing to your library.
- Networking: the default web port is 30013 on older releases or a port you pick on newer ones. Note it down.
Hit Install and give it a minute. TrueNAS pulls the image, creates the workloads, and the app status moves from Deploying to Running. Click the web portal link and you should see the Jellyfin welcome screen.
Running the setup wizard
The wizard walks you through creating an admin account, adding libraries, and picking a metadata language. When you add a Movies or Shows library, click the folder button and browse to /media, then into the subfolder that holds those files.
This is the exact spot where my first install fell apart. I browsed to a path that existed in the container but had nothing mounted behind it. If your media folders show up empty in this browser, stop and fix the mount before continuing, because the wizard will happily let you save an empty library.
Name your libraries clearly and let the scan run. A few thousand files can take five to fifteen minutes to pull artwork and metadata on the first pass.
GPU passthrough for smooth transcoding
Direct play is when your device just streams the file as-is, and it is free. Transcoding is when Jellyfin re-encodes on the fly because the client cannot handle the format, and on CPU alone that can pin every core and still stutter on 4K.
An Intel chip with Quick Sync or an Nvidia card changes the math completely. A modest Intel iGPU can handle several simultaneous 4K to 1080p transcodes while sitting near idle on the CPU.
In the Jellyfin app's edit screen on TrueNAS, scroll to the Resources or GPU Configuration section and allocate your GPU to the app. For Intel, this exposes the render device; for Nvidia, TrueNAS handles the driver plumbing if your card is detected under System, then Advanced.
| Hardware | Transcode method | Rough capacity |
|---|---|---|
| CPU only (older i5) | Software | 1 stream, may stutter on 4K |
| Intel iGPU (Quick Sync) | QSV / VA-API | 4-6 concurrent 1080p |
| Nvidia GTX 1650+ | NVENC | Many streams, patched driver removes limits |
After allocating the GPU, go into Jellyfin's own settings under Dashboard, Playback, Transcoding. Set hardware acceleration to Intel QuickSync or Nvidia NVENC to match your card, and enable the codecs you care about, like HEVC and H.264.
Testing that it actually works
Play a file, then open the Dashboard while it streams. You will see the active session and whether it says Direct Play or Transcode. Force a transcode by playing on a browser and lowering the quality bar, then watch your CPU graph in the TrueNAS reporting page.
If the CPU barely moves during a transcode, your GPU is doing its job. If it spikes to 90 percent, hardware acceleration is not engaging, and the usual culprit is a mismatched codec setting or a GPU that was allocated to the app but not selected in Jellyfin's playback menu.
For a deeper reference on the container itself, the official Jellyfin hardware acceleration docs break down which flags each GPU family needs. The TrueNAS Scale documentation is also worth bookmarking for app-specific quirks between releases.
Keeping it running long term
Because your config lives on its own dataset, take a ZFS snapshot of tank/apps/jellyfin before any big update. If an app upgrade ever breaks, you roll the snapshot back and you are exactly where you started, watch history and all.
Set the app to update on your schedule rather than blindly, and glance at the release notes when a new Jellyfin version lands. Most updates are painless, but the occasional database migration is worth doing when you have ten spare minutes, not right before movie night.
Six months from now you will forget any of this was hard. The setup that ate my first afternoon now takes me under ten minutes on a fresh box, and the difference is simply knowing that datasets, permissions, and GPU allocation are the three things to get right up front.
Frequently asked questions
Why does Jellyfin find no media even though the container is running?
Almost always this is a mount or permission problem. Confirm your media dataset is mounted to a path like /media inside the container, then browse to that exact path in the library setup. Also check that the apps user (UID 568) has read access to the dataset, since a permission block produces an empty scan with no obvious error.
Do I need a GPU to run Jellyfin on TrueNAS Scale?
No, Jellyfin runs fine on CPU alone if your client devices can direct play the files. You only need a GPU when many clients force transcoding or when you stream 4K to devices that cannot handle the source format. An Intel chip with Quick Sync is enough for most home setups.
Should the media mount be read-only?
For a pure playback server, read-only is the safer choice because Jellyfin can never modify or delete your files. If you want Jellyfin to write things like trickplay images or subtitles next to your media, leave it writable. Many people keep media read-only and let the config dataset hold everything Jellyfin needs to write.
How do I move from Plex to Jellyfin without redownloading everything?
Point Jellyfin at the same media dataset your Plex install already uses; the files never move. You will re-scan and rebuild metadata in Jellyfin, but the actual video files stay put. Watch history does not transfer between the two, so expect to start fresh on progress tracking.
Playback shows a black screen but audio still plays. What is wrong?
This usually means hardware decoding is enabled for a codec your GPU cannot handle, often HEVC. Go to Dashboard, Playback, Transcoding and disable HEVC hardware decoding, then test again. If it works, your card supports H.264 acceleration but not that particular HEVC profile.
Will an app update wipe my Jellyfin settings?
Not if your config lives on its own host-path dataset like tank/apps/jellyfin. Updates replace the container image but leave that dataset untouched. Take a ZFS snapshot of the config dataset before major version jumps so you can roll back if a database migration goes sideways.
