How to Back Up and Restore Jellyfin Before an Upgrade

Quick answer

Before upgrading Jellyfin, create its built-in backup, copy the archive away from the active Jellyfin data directory, and record the exact server version and installation method.

For stronger protection, also stop Jellyfin and copy its complete data and configuration paths while the service is offline.

Your recovery set should contain:

Jellyfin backup archive
+
offline data/configuration copy
+
matching Jellyfin version or Docker image
+
Compose file or package details
+
separate media backup where required

A backup is not proven until you can inspect it and complete a representative restore in an isolated environment.

Do this before preparing for Jellyfin 12 or any update that can migrate the database.

What a Jellyfin backup protects

Jellyfin 10.11 added a built-in backup feature. It can include:

• the Jellyfin database
• metadata and metadata images
• extracted or downloaded subtitles
• trickplay data stored by Jellyfin

The database is always included. Optional content can make the archive much larger.

A Jellyfin configuration backup does not automatically protect the original films, television episodes, music or books in your media folders. Back up irreplaceable media separately.

Also record external pieces the application archive may not explain on its own:

• current Jellyfin version
• native Ubuntu or Docker installation method
• package repository or image reference
• Docker Compose file and protected .env file
• host-to-container volume paths
• GPU device mappings and group permissions
• reverse-proxy or private remote-access configuration
• mounted storage and /etc/fstab

Step 1: record the running version

In Jellyfin, open:

Dashboard → General

For native Ubuntu packages:

dpkg -l | grep -E '^ii\s+jellyfin'
apt-cache policy jellyfin jellyfin-server jellyfin-web jellyfin-ffmpeg

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 your container uses another name.

The version matters because a database migrated by a newer Jellyfin release may not work with an older server. A rollback normally needs the old application version and its matching pre-upgrade data.

Step 2: create the built-in backup

Open:

Dashboard → Backups → Create Backup

Choose the components required and start the backup during a quiet period. Jellyfin checks for at least 5 GB of free space in the backup folder, but metadata, subtitles or trickplay can require more.

Confirm that the job completes and that a new ZIP archive appears.

Common default archive locations include:

Docker paths in that table refer to the host directory mapped to /config, not a literal host folder named /config.

Use docker inspect to find the real source path rather than guessing.

Step 3: copy the archive away from Jellyfin

An archive stored only inside the active Jellyfin data directory can disappear with the disk, volume or accidental deletion it is meant to protect against.

Copy it to at least one independent destination, such as:

• another physical disk
• a NAS or backup server
• encrypted off-site storage
• a removable disk that is disconnected afterwards

Keep the original filename and add a small text record containing:

Backup date:
Jellyfin version:
Installation method:
Host operating system:
Archive checksum:
Restore notes:

Create a checksum after copying:

sha256sum jellyfin-backup.zip

Run it again at the destination and compare the complete value.

Step 4: make an offline native Ubuntu copy

The default package paths normally include:

/var/lib/jellyfin
/etc/jellyfin

Confirm the actual service and paths before copying. Then stop Jellyfin so its database is not changing during the filesystem backup:

sudo systemctl stop jellyfin
systemctl is-active jellyfin

The second command should report inactive.

Copy the complete paths to a dated destination on another mounted filesystem:

sudo mkdir -p /mnt/backups/jellyfin/2026-09-01
sudo cp -a /var/lib/jellyfin /mnt/backups/jellyfin/2026-09-01/data
sudo cp -a /etc/jellyfin /mnt/backups/jellyfin/2026-09-01/config

Use your real verified backup mount and date. Check the destination before starting the copy; do not paste a placeholder path blindly.

Start the unchanged server again if the upgrade is not beginning immediately:

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

Step 5: make an offline Docker copy

First render and save the current Compose definition:

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

Protect the rendered file if it contains secrets.

Stop only the Jellyfin service:

docker compose stop jellyfin
docker compose ps jellyfin

Back up the host directory mapped to /config. Also retain:

• compose.yaml or docker-compose.yml
• protected .env and secret files
• current image name, tag, image ID or digest
• any separate metadata, cache or certificate paths required by your design

Do not back up only the container’s writable layer. Containers are replaceable; the persistent host path or named volume is the important data.

Restart the unchanged service if required:

docker compose start jellyfin
docker compose ps jellyfin

Use Jellyfin Docker Volume Paths Explained if the host and container paths are unclear.

Step 6: test the backup

At minimum:

1. list the archive contents
2. confirm the ZIP opens without an integrity error
3. verify the copied paths contain the database and configuration
4. compare the stored checksum
5. record the exact restore procedure

The strongest test is an isolated restore into a temporary VM or separate test container using the matching Jellyfin version.

Never point a test instance at the only production database. Do not let production and test servers write to the same data path.

A representative restore should confirm:

• Jellyfin starts
• users and libraries appear
• watched state is present
• plugins are recorded or recoverable
• a known library path can be mapped safely
• the restored database matches the backed-up application version

Restore from a built-in backup

Jellyfin supports restoring from the Backups page. Starting the restore causes the server to restart and become unavailable while recovery runs.

The server also supports starting with:

--restore-archive PATH_TO_BACKUP_ZIP

The exact service or container invocation depends on the installation method. Follow the documentation for the version being restored rather than improvising arguments on a production server.

Before restoring:

• stop normal household use
• preserve the current failed state and logs
• verify the archive checksum
• confirm the archive’s Jellyfin version
• confirm free disk space
• ensure no second Jellyfin instance uses the same data

Restore from a manual copy

A manual rollback requires the Jellyfin version that matches the backup.

The safe principle is:

stop Jellyfin
→ preserve the current data under a different name
→ copy, do not move, the backup into the expected paths
→ restore ownership and permissions
→ install or select the matching Jellyfin version
→ start once and inspect logs

Do not merge an older database into a partially migrated newer data directory. Restore the complete matching state.

For native Ubuntu, verify ownership after the copy:

sudo chown -R jellyfin:jellyfin /var/lib/jellyfin
sudo systemctl start jellyfin
sudo journalctl -u jellyfin -n 200 --no-pager

Do not recursively change ownership of your media library unless that is already the deliberate permissions design.

For Docker, restore the persistent /config source while the container is stopped, then recreate Jellyfin with the recorded image reference and unchanged Compose configuration.

Pre-upgrade checklist

• Current Jellyfin version recorded.
• Installation method and package/image recorded.
• Built-in backup completed.
• Archive copied away from the Jellyfin data path.
• Archive checksum verified.
• Native data/config or Docker /config copied offline.
• Compose, .env, mounts and GPU mappings recorded.
• Restore procedure tested or rehearsed in isolation.
• Matching old Jellyfin package or image reference retained.
• Media storage has its own backup plan.
• Upgrade and operating-system changes are in separate maintenance windows.

Official source

• Jellyfin backup and restore documentation

Related SmallGrid guides

• Jellyfin 12 Upgrade Guide
• How to Safely Update Jellyfin 10.11.x
• Jellyfin Docker Volume Paths Explained
• Back Up and Restore Docker Compose Services
• Backups That Don’t Lie: 3-2-1 for Home Servers

Recap

Use Jellyfin’s built-in backup, but do not leave the only archive inside the active server data directory. Copy it elsewhere, create an offline data/configuration backup, record the exact application version and prove that the recovery set can be restored.

For a major upgrade, rollback is the previous Jellyfin version plus its matching pre-upgrade data—not merely an older package or Docker tag.