A Pre-Upgrade Checklist for Jellyfin Containers and Dependencies

Before upgrading a Jellyfin container, preserve both sides of the deployment: the persistent Jellyfin state and the exact container definition that knows how to reach it. A new image is easy to pull; recovering a migrated database, changed mount, or forgotten device mapping is not.

Use the checklist in dependency order. First prove you can recover the data, then record the current image and runtime settings, then read the release path, and only then replace the image. Afterward, test the same libraries, users, playback modes, scheduled tasks, and restart behavior before deleting the rollback copy.

Record the Last Working Image and Container Definition

Save the current Jellyfin image tag and, when practical, its digest. Export or copy the Compose file or app definition that contains ports, networks, mounts, environment values, restart policy, user mapping, supplemental groups, GPU devices, and any reverse-proxy relationship.

The official Jellyfin container documentation distinguishes moving tags such as latest from explicit major, minor, and patch tags. Jellyfin image tag behavior A rollback is easier when you know the exact working version rather than only remembering that “latest worked yesterday.”

Do not prune the old image or delete the saved definition until the new version passes the complete validation window. If the upgrade fails before touching persistent data, the retained image and definition give you the least-invasive recovery path.

Create a Recoverable Backup of Jellyfin State

Protect the Jellyfin data and configuration directories before the image changes. The backup must be outside the live application path and readable independently; a second copy or snapshot on the same dataset is useful only if you understand what failure it protects against.

Jellyfin's backup documentation warns that upgrades can require restoring data because there is no general downgrade mechanism after migrations have been applied. It also documents built-in backups and the clean-stop requirement for manual file copies. Jellyfin backup and restore guidance

For a container workflow, the same principle is covered by ZimaSpace's pre-update rollback-point workflow. Stop here if you cannot identify the persistent paths or cannot verify the backup contents.

Capture Mounts, UID/GID, and Hardware Dependencies

List every bind mount and named volume and note whether it is read-only or writable. Record the runtime UID/GID, group memberships, and the ownership of Jellyfin-owned data directories. Also capture GPU or render-device mappings if hardware acceleration is enabled.

Jellyfin's container guide shows that media, config, and cache are mounted separately and that the container may run under a specified UID/GID. persistent paths and user mapping These values are dependencies, not decoration: a recreated container can start successfully while seeing an empty config directory or losing permission to a device.

Compare the saved definition with the effective running container, not just a template you think is current. If the runtime has manual changes that are missing from Compose or the NAS app definition, fix that drift before upgrading so the old deployment is reproducible.

Featured

ZimaCube 2 Personal Cloud Home NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

Check the Supported Upgrade Path and Plugin Risk

Read the release notes for every major boundary between the current version and target version. Look for required intermediate versions, database migrations, changed configuration, plugin compatibility, FFmpeg requirements, or long-running startup work.

Jellyfin's upgrade documentation repeatedly emphasizes backups and explains why schema changes can make a simple downgrade impossible. upgrade and downgrade boundaries Major release notes can add version-specific prerequisites, so do not infer a safe jump from the fact that the container image exists.

If a plugin is essential, confirm that a compatible version is available before the server upgrade. If a plugin is optional and has a history of blocking startup, record its current version and be prepared to disable only that plugin if the new server logs identify it as the failure source.

Perform the Upgrade Without Changing the State Boundary

Stop Jellyfin cleanly, pull the intended image, and recreate only the Jellyfin service with the same verified persistent paths and runtime dependencies. Do not combine the upgrade with a storage migration, UID/GID redesign, reverse-proxy rewrite, and GPU reconfiguration unless those changes are the actual purpose of the maintenance.

Watch the first startup log. A migration may legitimately take time on a large library, while an immediate “permission denied,” empty database, missing path, or incompatible schema message points to a different branch. Do not repeatedly restart a migration simply because the UI is not immediately available.

If the container opens as a fresh server, stop it before configuring anything. That symptom usually means the new service is pointed at the wrong persistent state. Correct the mount mapping first; configuring a new empty instance can create new files that obscure the recovery path.

Validate the New Version Before Removing Rollback Assets

Verify the original server identity, users, libraries, metadata, and important settings. Play one Direct Play item and one representative transcode, then run or observe a scheduled task that matters to your setup. Check logs for recurring migration, database, permission, and FFmpeg errors.

Restart the container once after the first successful session. The new version is not fully validated until it can reopen the same data and devices from a clean recreation or restart. This catches accidental reliance on a transient mount or runtime state.

Keep the pre-upgrade backup, previous image reference, and saved definition until the server has passed its normal workload window. If rollback is required after a database migration, follow Jellyfin's documented restore boundary instead of pointing an older image at already-migrated state.