Jellyfin 12 Upgrade Guide: 10 Things to Check Before You Update

Quick answer

Jellyfin 12.1 was released on 15 September 2026, one week after 12.0, with 47 server fixes. Jellyfin 12.2, a minor bug-fix release, followed on 5 October 2026. If you are moving from Jellyfin 10.10.7 or 10.11.x, the major migration rules introduced with 12.0 still apply.

Update, 9 October 2026: Jellyfin 12.2 was released on 5 October 2026 as a minor bug-fix release. The steps in this guide still apply. For the 12.2 update procedure and troubleshooting, see Jellyfin 12.2 Update Guide: Fix Scanning, Crashes and Docker Problems.

Before upgrading a working household server, make it recoverable. Record the current version and installation method, create a tested backup, remove incompatible third-party plugins, capture storage and hardware-acceleration settings, and write down the exact rollback procedure. Jellyfin warns that the 12.x migration rewrites database data and that returning to the previous version requires the matching pre-upgrade backup. Follow How to Back Up and Restore Jellyfin Before an Upgrade for the complete native and Docker recovery process.

The safe sequence is:

prepare on your supported 10.10.7 or 10.11.x version
→ read the Jellyfin 12.0 migration notes and 12.1 release notes
→ take a final offline backup
→ remove incompatible third-party plugins
→ upgrade only Jellyfin
→ allow migrations to finish
→ allow the required full library scan to finish
→ verify libraries, users and playback
→ keep the old version and backup until the upgrade proves stable

Jellyfin 12.1 and 12.2 are stable point releases of the 12.x line. Jellyfin supports the direct 12.x upgrade path from 10.10.7 or any 10.11.x release.

If you are already on 12.0, take a fresh backup and move to the latest 12.x point release rather than treating 12.0 as the preferred long-term point release. If you have already upgraded and the server is rescanning, plugins disappeared, media looks missing or the web interface looks wrong, use Jellyfin 12 Upgrade Problems: What to Check After Updating. For high CPU, memory growth or scan loops, use Jellyfin 12 High CPU, Memory and Scan Problems: What to Check.

---

Why Jellyfin 12 needs preparation

Jellyfin 12 is the release after 10.11. The project has dropped the permanent 10. prefix, so there is no Jellyfin 10.12.

The release focuses heavily on performance. Jellyfin reports improvements to slow queries and loading in folder-based libraries, collections, music libraries, playlists and the homepage.

It also performs migrations during the first startup. Jellyfin warns that an older server cannot normally use data after a newer version has migrated it. Returning to the previous version therefore means restoring the matching pre-upgrade data, not merely reinstalling an old package or changing a Docker tag.

The major migration arrived with 12.0, and 12.1 and 12.2 are now stable point releases. The first startup from 10.11 still performs database migrations, the first library scan is intentionally more thorough and third-party plugins built for 10.11 must be removed before the upgrade unless compatible 12.x builds are available.

---

1. Check the current version and installation method

Open:

Dashboard → General

Record the server version shown there.

For native Ubuntu packages:

dpkg -l | grep -E '^ii\s+jellyfin'
apt-cache policy jellyfin jellyfin-server jellyfin-web
systemctl status jellyfin --no-pager

For Docker:

docker inspect jellyfin --format '{{.Config.Image}}'
docker inspect jellyfin --format '{{.Image}}'
docker inspect jellyfin --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

Replace jellyfin if the container has another name.

Write down:

Jellyfin version:
Install method:
Package repository or image:
Configuration/data path:
Media paths:
Plugins:
GPU devices:
Remote-access method:

Do not change installation method during the Jellyfin 12 upgrade. Moving from native packages to Docker is a separate migration.

2. Reach a healthy stable starting point

Fix existing problems before the major upgrade.

Your current Jellyfin server should:

• start without repeated errors
• complete a library scan
• show the expected users and libraries
• play a known Direct Play file
• complete one known transcode, if transcoding is used
• see every expected media mount after reboot
• have enough free disk space for backups and migrations

Check:

df -hT
findmnt
systemctl --failed

Jellyfin’s supported direct upgrade path to 12.x starts from 10.10.7 or any 10.11.x release. If the server runs an older release, bring it to a supported starting point first. Do not combine that maintenance, an Ubuntu release upgrade and the Jellyfin 12 migration in one window.

Check for usernames that differ only by capitalisation

Jellyfin 12 makes usernames case-insensitive. Before upgrading, check that you do not have accounts whose names differ only by capitalisation, such as:

Sean
sean

Those names were distinct before Jellyfin 12, but they collide under the new case-insensitive rule and can cause the database migration to fail.

Review the user list before the upgrade and rename or remove any duplicate-by-case accounts so every username remains unique when case is ignored.

3. Create a backup you can actually restore

Jellyfin 10.11 includes a built-in backup system under:

Dashboard → Backups

Create a backup during low activity, then copy the resulting archive away from the active Jellyfin data directory and preferably away from the server.

For an additional filesystem-level backup, stop Jellyfin first.

Native Ubuntu

Default paths normally include:

/var/lib/jellyfin
/etc/jellyfin

Stop the service before copying them:

sudo systemctl stop jellyfin
systemctl is-active jellyfin

Copy both directories to a protected, dated backup destination, then start the current version again if the upgrade is not immediate:

sudo systemctl start jellyfin
systemctl status jellyfin --no-pager

Docker

Stop only Jellyfin:

docker compose stop jellyfin
docker compose ps jellyfin

Back up:

• the host directory mapped to /config
• the Compose file
• the .env file and secrets, stored securely
• any separate cache or metadata paths needed by the deployment
• the current image reference and image ID

Then restart the unchanged service if required:

docker compose start jellyfin
docker compose ps jellyfin

A backup is not proven until representative files or the complete instance have been restored in isolation.

4. Decide the Docker image strategy

Jellyfin 12.1 and 12.2 are available through the stable release channel.

For the production server:

• keep the current image reference unchanged while preparing
• record the current immutable image ID or digest
• read the 12.0 migration notes and 12.1 release notes before pulling
• confirm your pre-upgrade server is 10.10.7 or 10.11.x
• take the final backup before changing the image
• remove incompatible third-party plugins
• update only the Jellyfin service
• do not pull Sonarr, Radarr or other containers in the same window

Before the stable update, record the rendered Compose configuration:

docker compose config > compose-effective-before-jellyfin-12.yaml
docker compose config --images

Protect the rendered file if it contains secrets.

Use the tag policy already defined in your Compose file. If you pin exact versions, change the Jellyfin image deliberately. If you follow a floating stable tag, confirm what it resolves to before the pull so the major upgrade is intentional.

5. Check the native Ubuntu package route

Jellyfin 12.1 and 12.2 are stable releases, so you do not need to move a production server onto an unstable repository to receive it.

Before the stable upgrade:

apt-cache policy jellyfin jellyfin-server jellyfin-web jellyfin-ffmpeg
grep -RhsE '^(deb |Types:|URIs:|Suites:|Components:|Signed-By:)' \
  /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null

Record the repository and candidate packages. Confirm that the normal Jellyfin repository offers the intended 12.1 or 12.2 packages for your Ubuntu release before running the upgrade.

Do not combine this with an Ubuntu 24.04-to-26.04 release upgrade. Prove the operating system first, then change Jellyfin in a separate maintenance window.

6. Audit plugins and external integrations

Open:

Dashboard → Plugins → My Plugins

Record every plugin, its version and its repository.

Jellyfin’s 12.0 release notes explicitly tell users to remove third-party plugins before upgrading. Plugins built for 10.11 will not load on 12.x unless their authors have published compatible versions.

Before upgrading:

• check whether each plugin explicitly supports Jellyfin 12
• record custom plugin repositories
• remove third-party plugins that are not confirmed compatible
• record integrations that use Jellyfin’s API or credentials
• plan to reinstall only compatible plugin builds after the server itself is healthy

Official plugins have been updated for Jellyfin 12 support. Treat third-party plugin recovery as a separate post-upgrade task rather than blocking the core server migration.

7. Record FFmpeg and hardware-acceleration settings

Capture a repeatable playback baseline before the upgrade:

Client:
Test file:
Playback mode:
Video codec:
Audio codec:
Subtitles:
GPU and acceleration method:

For Docker:

docker inspect jellyfin --format '{{json .HostConfig.Devices}}'
docker exec jellyfin /usr/lib/jellyfin-ffmpeg/ffmpeg -version 2>/dev/null | head
docker exec jellyfin ls -la /dev/dri 2>/dev/null

For native Ubuntu packages:

dpkg -l | grep -E '^ii\s+jellyfin-ffmpeg'
ls -la /dev/dri 2>/dev/null
getent group render video

Jellyfin 12 ships with Jellyfin FFmpeg 8.1, so record the pre-upgrade FFmpeg version as part of the baseline and expect the bundled media stack to change with the major release.

After the upgrade, replay the same file on the same client. Use Jellyfin Direct Play vs Transcoding to interpret the result rather than assuming high CPU means the database migration failed.

8. Plan for first-start migrations

Jellyfin says the first Jellyfin 12 startup runs migrations and can take several minutes.

During that first start:

• do not repeatedly restart the server
• do not interrupt the container because the web page is slow
• follow the service or container logs
• watch memory, CPU and disk activity
• allow a longer maintenance window than a normal patch update
• use local access where possible

Native Ubuntu monitoring:

sudo journalctl -u jellyfin -f
systemctl status jellyfin --no-pager

Docker monitoring:

docker compose logs --timestamps --follow jellyfin
docker stats jellyfin

If resource use grows without settling or the service repeatedly fails, preserve the logs and stop. Do not keep restarting until the backup and recovery plan have been checked. Use Jellyfin 12 High CPU, Memory and Scan Problems: What to Check for the focused performance and scan workflow.

9. Prove storage paths and permissions

A major upgrade cannot repair an unavailable mount, wrong Docker path or blocked parent directory.

Before upgrading, verify native Jellyfin access:

findmnt
sudo -u jellyfin find /path/to/media -maxdepth 3 -type f | head -20
namei -l /path/to/media

For Docker, compare host and container paths:

docker inspect jellyfin --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
docker exec jellyfin find /media -maxdepth 3 -type f | head -20

Use the real container media path in the second command.

If these checks fail, fix the storage layer first:

• Jellyfin Docker Volume Paths Explained
• Jellyfin Docker Permissions
• Jellyfin Library Not Showing Files
• Jellyfin Troubleshooting Hub

Do not use chmod 777 as an upgrade workaround.

10. Write the validation and rollback plan

The rollback unit is:

previous Jellyfin version
+
matching pre-upgrade data and configuration

Changing only a Docker tag or reinstalling an old package is not a valid rollback after migrations have changed the database.

Write down, before upgrading:

• the command that stops Jellyfin
• the previous package version or immutable image reference
• the exact backup path
• the restore commands
• how ownership and permissions will be restored
• how the old server will be prevented from touching migrated data
• how success will be verified before household access resumes

After Jellyfin 12.1 starts, check:

• the dashboard reports the intended stable version
• startup migrations complete without repeated errors
• CPU and memory use settle
• users, watched status and favourites remain present
• library counts look credible
• a manual scan completes
• the baseline Direct Play file behaves as before
• a known transcode works, if used
• subtitles work
• hardware acceleration uses the expected device
• plugins and integrations behave normally
• remote access works through the intended route
• the result survives a controlled reboot

Keep the backup and previous application reference until the new server has proved stable.

---

Should you upgrade to Jellyfin 12.1 now?

Jellyfin 12.1 contains dozens of fixes over 12.0, and Jellyfin 12.2 has since followed as a minor bug-fix release. Jellyfin’s normal versioning policy is to move users toward the latest supported point release rather than remain on the initial minor release indefinitely.

For a normal household server, the safe decision is upgrade deliberately:

• start from 10.10.7 or 10.11.x when making the major migration
• take and preserve a tested backup
• remove incompatible third-party plugins
• target the latest stable 12.x point release (12.1 or 12.2) rather than 12.0
• allow database migrations to finish
• allow the first full library scan to complete
• hard refresh the web client if the UI looks wrong
• verify playback and hardware acceleration before declaring success

If you are already on 12.0, take another backup and review the changelog for the point release before applying it. If the server has no tested backup, an unsupported starting version or essential plugins without Jellyfin 12 builds, fix those conditions before upgrading.

---

Official sources

• Jellyfin Server 12.2 release
• Jellyfin Server 12.1 release
• Jellyfin 12.0 release notes
• Jellyfin backup and restore
• Jellyfin upgrade and downgrade warnings

---

Related SmallGrid guides

• Jellyfin 12.2 Update Guide: Fix Scanning, Crashes and Docker Problems
• Jellyfin 12 stable release update
• Jellyfin 12 Upgrade Problems: What to Check After Updating
• Jellyfin 12 High CPU, Memory and Scan Problems: What to Check
• Jellyfin on Ubuntu hub
• How to Safely Update Jellyfin 10.11.x
• Jellyfin Docker Volume Paths Explained
• Jellyfin Docker Permissions
• Jellyfin Library Not Showing Files
• Jellyfin Direct Play vs Transcoding
• Jellyfin Troubleshooting Hub
• Backups That Don’t Lie: 3-2-1 for Home Servers

---

Recap

Jellyfin 12.1 and 12.2 are now stable point releases, but the major-upgrade preparation rules introduced with 12.0 still matter.

Build a known-good starting point, create a restore-tested backup, remove incompatible third-party plugins, record paths and hardware settings, allow for first-start migrations and the required full library scan, and treat rollback as the previous application plus its matching data. Target the latest stable 12.x point release, verify the complete server, and keep the recovery copy until the new version has proved stable on your system.