Jellyfin 12.0, released 8 September 2026, is the first major release to drop the old 10.x numbering, and it forces a one-way database migration. Back up your config directory first, then move from a supported 10.10.7 or 10.11.x base, and the upgrade is a routine 20-minute job. Done in the right order, your library, plugins, and users survive intact.
Plex's closed model left a large community running Jellyfin as their personal media hub, and 12.0 is the biggest maintenance window most of that community has hit. This guide walks through why the version number changed, what to check before you pull the new image, the exact Docker and native steps, and how to back out if something goes wrong.
I verified the upgrade requirements directly against the Jellyfin 12.0 release announcement and cross-referenced them with the GitHub release notes. The numbers hold up: minimum base of 10.10.7, a one-way migration, and legacy routes removed in the same release.
Key Takeaways
Jellyfin 12.0 dropped the 10.x prefix. It was originally going to ship as 10.12.0, but the team reset the major number.
You must be on 10.10.7 or any 10.11.x before upgrading. Older bases cannot migrate directly.
The database migration is one-way. Take a full backup of your config directory before you start.
Run a full library scan after upgrading. The first one takes noticeably longer than usual.
Modern UI is now the default, and legacy /emby/ routes plus .NET 9 plugins are gone.
Why the version jumped to 12.0
Jellyfin kept its 10.x scheme for years, even as the feature set outgrew the label. 12.0 was going to be tagged 10.12.0, but the team reset the major number to signal the scale of the change. As of release day the server reports 12.0.0, and 10.11.x remains the last branch carrying the old numbering.
The jump is not cosmetic. It moves the runtime to .NET 10 (up from .NET 9) and FFmpeg to 8.1 (up from 7.1.4). That combination is why the migration is one-way and why you need a supported base version. Husham broke down the should-you-upgrade trade-offs and concluded most people on a current 10.11.x base should move.
Pre-upgrade checklist
Run this list in order before you touch the server. Each step reduces the chance that you are stuck with a broken install and no way back.
Stop the Jellyfin service and make a full manual backup of both your data and config directories. This is your only rollback path.
Confirm your current version. You must be on 10.10.7 or any 10.11.x release. Anything older cannot be migrated directly.
Check your usernames. Names are now case-insensitive, so two users that differ only by capitalization will fail the migration.
Remove third-party plugins. They need 12.0 builds and can block the update.
Plan for a full library scan afterward, because the first scan takes significantly longer once auto-resolved alternate versions are cleared.
If your stack is one of those small home-lab boxes, the same backup discipline applies to every container you run. Our guide to self-hosting on a Raspberry Pi 5 covers taking full image-level backups of a whole media stack, which is the safest safety net for a one-way migration like this.
Docker and native upgrade steps
Docker with compose is the most common self-host setup, so start there.
`# 1. Stop and back up the config directory
docker compose stop jellyfin
tar -czf ~/jellyfin-backup-$(date +%F).tar.gz config
2. Point the image tag to 12.0 in compose.yaml
3. Optional: run the migration in isolation first
docker compose run --rm jellyfin --mode MigrateSystem
4. Start the container
docker compose up -d`
Once it is up, run a full library scan from the admin panel, then do a hard refresh in your browser with Ctrl+Shift+R or clear the web cache, and reinstall any plugins from the stable repository. Jacar.es walked through the same Docker path with an eye on keeping a working rollback tag available.
Native installers for Debian, Ubuntu, Snap, and Windows follow the same logic: stop the service, back up config, install the 12.0 package, then start and rescan. One caveat: Debian Bullseye and Ubuntu Focal packages are no longer built for 12.0, so users on those distros need to move to a supported release first. Because the first scan rewrites a lot of library metadata to disk, it is worth pairing this with the SSD overprovisioning tweak if your library sits on a solid-state drive.
What changed in Jellyfin 12.0
The headline features are books and comics support, now built into the server with no plugin required. Playlists are relational, meaning every item is its own database row instead of a flat list. The Modern UI is promoted to the default look, with the older layout rebranded as Legacy and still available if you prefer it.
Under the hood, ListenBrainz ships bundled for music similarity and recommendations, plugins can now extend search results through new search providers, and subtitle settings moved to a per-library model with the global config removed. Multiple versions are now supported for episodes, not just movies. Free-Codecs called the faster library and new look the two things users will notice first, and that matches what the release notes emphasize.
Breaking changes and how to roll back
Before you upgrade, know what you are losing. Legacy /emby/ and /mediabrowser/ routes are removed, so old clients that hit those paths stop working. Legacy authorization is disabled by default. Usernames being case-insensitive means duplicate-by-capitalization pairs will block the migration. Plugins must be rebuilt for .NET 10. Image endpoints no longer upscale beyond the source resolution, and .ogg is treated as audio only, not video. Global subtitle settings are gone in favor of per-library ones.
Because the database migration is one-way, your rollback is not a simple version downgrade. It is a restore from the backup you took in the checklist. On Docker, that looks like this:
`docker compose down
mv config config.12-failed
tar -xzf ~/jellyfin-backup-YYYY-MM-DD.tar.gz
set the compose image tag back to 10.11.11
docker compose up -d`
Do not skip the backup step to save five minutes. If the migration fails partway, the restored config directory is the only thing that puts you back on a known-good 10.11.x state.
Conclusion
Make the move to 12.0 for the security fixes first, not just for the new books support. The .NET 10 and FFmpeg 8.1 runtimes ship security patches, and that is the real reason the project recommends upgrading. The risk sits almost entirely in the one-way migration, and that risk is neutralized by a single habit: stop the service, back up config, then upgrade. Follow the checklist in order and the job is short and predictable. What did your first post-upgrade library scan look like, or is there a plugin that still has no 12.0 build? Share your experience in the comments.
Frequently asked questions
Can I upgrade Jellyfin straight from 10.9 to 12.0?
No. You must be on 10.10.7 or any 10.11.x release first. Older bases cannot be migrated directly, so move to a supported 10.x version before pulling 12.0.
What happens if I forget to back up before the one-way migration?
You lose your rollback path. The database migration cannot be reversed, so without a backup of your config directory a failed upgrade leaves you rebuilding from the database rather than restoring a known-good state.
Will my old clients that use the /emby/ route keep working?
No. The legacy /emby/ and /mediabrowser/ routes are removed in 12.0, so any client that depends on those paths will stop working until it points at the new routes.
Why is the first library scan after upgrading so slow?
Auto-resolved alternate versions are cleared on the upgrade, so the first full scan has to rework more of your library. It can also mark some movies as newly added. That is expected behavior, not a failure.
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "Can I upgrade Jellyfin straight from 10.9 to 12.0?",
"acceptedAnswer": {
"@type": "Answer",
"text": "No. You must be on 10.10.7 or any 10.11.x release first. Older bases cannot be migrated directly, so move to a supported 10.x version before pulling 12.0."
}
},
{
"@type": "Question",
"name": "What happens if I forget to back up before the one-way migration?",
"acceptedAnswer": {
"@type": "Answer",
"text": "You lose your rollback path. The database migration cannot be reversed, so without a backup of your config directory a failed upgrade leaves you rebuilding from the database rather than restoring a known-good state."
}
},
{
"@type": "Question",
"name": "Will my old clients that use the /emby/ route keep working?",
"acceptedAnswer": {
"@type": "Answer",
"text": "No. The legacy /emby/ and /mediabrowser/ routes are removed in 12.0, so any client that depends on those paths will stop working until it points at the new routes."
}
},
{
"@type": "Question",
"name": "Why is the first library scan after upgrading so slow?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Auto-resolved alternate versions are cleared on the upgrade, so the first full scan has to rework more of your library. It can also mark some movies as newly added. That is expected behavior, not a failure."
}
}
]
}
Top comments (0)