Skip to content

Upgrading Jellyfin to Version 12.0: Migration Guide

A cozy, dimly lit living room at night with a television displaying the Jellyfin media server interface, a sofa draped with a knit blanket, and a coffee mug with a retro sci-fi insignia resting on a table.

Jellyfin 12.0 changes how major updates are numbered, moving away from the old 10.x.y scheme used since 2018. Previously, massive under-the-hood overhauls, like rewriting the entire database structure were bundled into point releases like 10.11. Because the version number barely changed, many installations treated it like a routine minor patch, upgraded without backing up, and ran into trouble when things broke.

To make it immediately obvious when an update contains major, breaking changes, the project dropped the leading “10” prefix entirely and jumped straight to version 12.0.

Pre-Upgrade Checklist

  • Check Base Version: Ensure you are running a stable 10.x release (such as 10.10.x or 10.11.x) before upgrading. Extremely outdated installations (such as early 10.8.x or older) should be updated to a recent 10.x version first to ensure smooth database translation.
  • Take a Full Backup: Stop the container and make a manual copy of the configuration directory before doing anything else. Version 12 rewrites parts of the database on first boot, meaning a rollback is impossible without a backup.
  • Remove Incompatible Plugins: Third-party plugins built for the 10.x series will not work on version 12 and can cause boot loops. Remove them prior to upgrading and grab updated builds later. Official plugins will update automatically.
  • Check Usernames: Usernames are now case-insensitive. If two user accounts differ only by capitalisation (such as “Admin” and “admin”), the database migration will fail. Resolve any conflicts beforehand.

Docker Step-by-Step Upgrade Procedure

Step 1: Stop the Container and Back Up Files

Navigate to the directory containing your Docker Compose file, stop the running container, and back up the configuration path:


cd /path/to/your/jellyfin
docker compose down
cp -r config config_backup
Step 2: Pull and Start the Container

Pull the updated image and start the container using either Docker or Docker Compose:

Docker:


docker pull jellyfin/jellyfin
docker run -d \
 --name jellyfin \
 --user uid:gid \
 -p 8096:8096/tcp \
 -p 7359:7359/udp \
 --volume /path/to/config:/config \ # Alternatively --volume jellyfin-config:/config
 --volume /path/to/cache:/cache \ # Alternatively --volume jellyfin-cache:/cache
 --mount type=bind,source=/path/to/media,target=/media \
 --restart=unless-stopped \
 jellyfin/jellyfin

Docker Compose:


docker compose pull
docker compose up -d
Step 3: Monitor Migration Logs

Review the startup logs to ensure database migrations complete successfully:


docker compose logs -f jellyfin

Allow the process to run until initialization finishes.

Step 4: Post-Upgrade Actions
  • Clear Web Cache: Perform a hard browser refresh (Ctrl + Shift + R) to clear outdated cached assets.
  • Run a Full Library Scan: DO NOT SKIP THIS STEP. Because alternate media version linkages are wiped out during the upgrade, you must trigger a full library scan to rebuild relationships and fix catalogue indexing. Expect this scan to take significantly longer than a standard library update as the server re-indexes everything under the new architecture.
  • Expect Plugin Initialisation Delays: Reinstalling or updating plugins on version 12 can trigger a prolonged restart phase. If the container appears to hang on the startup screen after plugin installation, let it sit and process the background initialisations without interrupting the service.

Join the conversation

Related Stories

Tags: , , , ,