Jellyfin 12 is the biggest Jellyfin release in years. It dropped the "10." from the version number, rewrote parts of the database, and changed enough under the hood that the developers put the backup warning in capital letters. My own server is on 12.4.0 now. If you're still on 10.10 or 10.11, this is how to get across without losing your library, watch history or users.
The upgrade itself is just a new version. The work is the preparation: the right starting version, a real backup, removing plugins that won't load, and two small changes that can lock users out if you don't check them first.
Quick answer
To upgrade to Jellyfin 12, you must be on 10.10.7 or any 10.11.x first. Stop Jellyfin and make a full copy of its data and config folders, because 12.0 rewrites the database on first start and the backup is the only way back. Remove third-party plugins (10.11 builds won't load on 12), check that no two usernames differ only by capital letters (the migration fails if they do), then update the container or package and let the first start finish without interrupting it. Run a full library scan afterwards. Old clients using the /emby/ address stop working.
What changed in Jellyfin 12
The official 12.0 release post is long. These are the parts that affect an upgrade:
| Change | What it means for you |
|---|---|
| New version numbers (10.12 became 12.0) | Anything that reads the version, such as a monitoring check or a pinned Docker tag, may need updating |
| Database schema changes on first start | No going back without a backup |
| Server now targets .NET 10 | Third-party plugins built for 10.11 won't load. Official plugins are updated |
/emby/ and /mediabrowser/ addresses removed, old sign-in method disabled | Very old or Emby-era client apps stop signing in |
| Usernames are now case insensitive | If "Ram" and "ram" both exist, the migration fails |
| Full library scan required after upgrade | First scan is slower, and some movies may show as newly added |
Subtitle settings now per library, .ogg treated as audio | Check subtitle settings on each library afterwards |
The nice parts: faster browsing on large libraries, alternate versions for episodes, proper book and comic libraries, FFmpeg 8.1, and the new "Modern" web layout as the default (the old one is still there as "Legacy").
Step 1: Check where you're starting from
In the Jellyfin web UI, go to Dashboard. The server version is on the main page. Or from any machine on your network:
curl -s http://192.168.0.50:8096/System/Info/Public
That returns a small JSON with "Version". You need 10.10.7 or any 10.11.x. If you're on something older, upgrade to 10.10.7 first, start it once, then continue.
Step 2: Clean up usernames and plugins
Do this while you're still on 10.x, because afterwards it's too late.
- Usernames: open Dashboard > Users and look for any two accounts whose names differ only by capital letters. Rename or delete one. The 12.0 migration fails if it finds a pair.
- Plugins: open Dashboard > Plugins. Write down what you have, then uninstall the third-party ones (anything not from the official Jellyfin repository). Reinstall them after the upgrade once their developers have released versions for 12.
- Clients: if anyone in the house uses an old app that connects through an
/emby/address, warn them now, or find them a current Jellyfin client.
Step 3: Stop Jellyfin and back it up
The release notes ask you, in capitals, to stop Jellyfin and take a full manual backup of the data and config directories. A copy taken while Jellyfin is running can be inconsistent, so stop it first.
For Docker or Docker Compose:
docker compose stop jellyfin
sudo tar czf /backups/jellyfin-$(date +%F).tar.gz /path/to/jellyfin/config /path/to/jellyfin/data
Use the paths from your own compose file. Many setups keep everything under one config folder, which is fine, just back up whatever is mounted into the container. The media files themselves don't need backing up for this. Jellyfin doesn't change them.
On TrueNAS, the simplest approach is a ZFS snapshot of the dataset that holds the Jellyfin app's config (with the app stopped). Rolling back a snapshot is far quicker than restoring a tarball.
Step 4: Upgrade
For Docker, if your compose file pins a version tag, change it to the 12.x version you want. If it uses latest, just pull:
docker compose pull jellyfin
docker compose up -d jellyfin
docker compose logs -f jellyfin
On TrueNAS or another app platform, use its update button for the Jellyfin app. On a Debian or Ubuntu package install, sudo apt update && sudo apt upgrade with Jellyfin's repository.
Then watch the log and don't stop the server while migrations are running. The release notes warn about this specifically. On a big library the first start can take a while. Wait until the web UI comes up.
Step 5: After the upgrade
- Open Dashboard and confirm the new version.
- Run a full scan: Dashboard > Libraries > Scan All Libraries. The release notes say a full scan is required.
- Check subtitle settings on each library, since they're per library now.
- Reinstall the plugins you need once versions for 12 exist.
- Sign in from each type of device you use (TV, phone, browser) to make sure the apps still connect.
If you use Seerr, Radarr or Sonarr with Jellyfin, test that they can still reach it. Seerr still works with my 12.4 server, but anything that checks Jellyfin's version number is worth a look.
What can go wrong
- Migration failed on start. Check the log for the username conflict first. If that's it, roll back (below), fix the usernames on 10.x, and try again.
- A plugin is missing. Expected for third-party plugins. Wait for a version built for 12.
- The TV app won't sign in. Old clients that used the removed sign-in method or
/emby/paths need updating. Current official Jellyfin apps work. - Library looks wrong or half empty. Let the full scan finish before judging. The first scan after 12.0 is slower and may mark some movies as new.
How to roll back
Stop Jellyfin, restore the config and data folders from your backup (or roll back the ZFS snapshot), set the image or package back to the exact version you had before, and start it. A 12.x database won't open on 10.11, so the backup has to be from before the upgrade. That's the whole reason for Step 3.
A few things I learned
- Snapshots beat tarballs on TrueNAS. Stop the app, snapshot the dataset, upgrade. Rolling back takes seconds.
- Check usernames first. It's a strange thing to fail on, and it's easy to fix before the upgrade and annoying after.
- Don't pin
10.*tags. With the new numbering, a version filter that expects "10." will never see 12.
If you're building a Jellyfin setup from scratch, my Jellyfin movie automation with a Discord approve button shows how mine fetches films after I approve them, and the TrueNAS home server post covers the storage it runs on. To reach it from outside the house, see Cloudflare Tunnel for TrueNAS. Everything else is in Homelab Intelligence, and if you'd like help setting up a media server, that's on my services page.
Frequently asked questions
Can I upgrade Jellyfin 10.11 directly to 12?
Yes. Jellyfin 12.0 supports upgrading directly from 10.10.7 or any 10.11.x release. Older versions must go to 10.10.7 first. Stop Jellyfin and back up the data and config folders before upgrading, because the database is rewritten on first start.
Why did my Jellyfin 12 migration fail?
A common cause is two usernames that differ only by capital letters, because usernames are case insensitive in Jellyfin 12. Restore your backup, rename one of the accounts on 10.x, and upgrade again. Check the server log for the exact error.
Do Jellyfin plugins work on version 12?
Official plugins are updated for 12. Third-party plugins built for 10.11 will not load because the server now targets .NET 10. Remove them before upgrading and reinstall them once their developers release versions for Jellyfin 12.
Why did Jellyfin skip from 10.11 to 12?
Jellyfin dropped the leading 10 from its version numbers, so what would have been 10.12.0 is now 12.0. The server reports 12.0.0 or later. Anything that parses the version, such as monitoring or pinned Docker tags, may need updating.
How do I roll back a Jellyfin 12 upgrade?
Stop Jellyfin, restore the config and data folders from the backup taken before upgrading, set the container or package back to the exact previous version, and start it. A database already migrated to 12 cannot be opened by 10.11.
