How to Update Jellyfin Docker Container in 5 Steps Without Breaking Anything

If you’re running Jellyfin on a home server inside Docker, you’ve probably stared at a “new version available” notification wondering — is it safe to update? Will I lose my library? My watch history? My metadata? 😅

This post covers exactly how I update Jellyfin Docker container on my server without losing a single thing. The steps apply whether you started with docker run or Docker Compose.

If you’re still new to Docker basics — volumes, images, compose files — check out my Docker for Beginners guide first. It’ll make this guide much easier to follow.

Before You Start: Check Your Container Structure

The most important thing before you update Jellyfin Docker container: your config and media must live outside the container in mounted volumes. Containers are ephemeral — when you remove one, everything inside it is gone.

Check what you’ve got:

docker inspect jellyfin

Look for the Mounts section. You should see two host paths mapped into the container:

📁 Config directory — Jellyfin’s database, metadata, plugins, user data
🎞️ Media directory — your actual movies, shows, music

If your config has no bind mount and lives inside the container — stop here and fix that first. Updating will wipe everything. 🚨

Step 1 — Back Up Your Config Directory

Everyone says it, most people skip it. Don’t.

The Jellyfin config folder is usually a few hundred MB but it holds your entire library database, watch history, ratings, and plugin settings. Losing it means starting from scratch. 🙅

# Replace with your actual config path
cp -r /opt/jellyfin/config /opt/jellyfin/config_backup_$(date +%Y%m%d)

# Confirm the backup is there
ls -lh /opt/jellyfin/

The $(date +%Y%m%d) stamps the backup with today’s date automatically. You can keep multiple versions without confusion, and disk space is cheap. 😌

Step 2 — Stop and Remove the Old Container

This sounds scary but it’s safe. We’re removing the container — not the data. Your volumes stay on the host filesystem completely untouched.

docker stop jellyfin
docker rm jellyfin

Step 3 — Pull the New Jellyfin Image

To update Jellyfin Docker container you need to pull the latest image first. There are two popular Jellyfin Docker images. Use whichever one you originally installed:

# Official Jellyfin image
docker pull jellyfin/jellyfin:latest

# Or LinuxServer image
docker pull lscr.io/linuxserver/jellyfin:latest

Not sure which one you used? Check the Image field in docker inspect jellyfin output before you stop it.

Official Docker installation docs: https://jellyfin.org/docs/general/installation/container 📚

Step 4 — Recreate the Container

Use the same volumes, same ports, same environment variables — just a fresh image underneath.

Option A — docker run

docker run -d \
  --name jellyfin \
  -p 8096:8096 \
  -v /opt/jellyfin/config:/config \
  -v /mnt/media:/media:ro \
  --restart unless-stopped \
  jellyfin/jellyfin:latest

Adjust the volume paths to match your actual setup.

Option B — Docker Compose (recommended 🏆)

If you’re not using Docker Compose yet — this is your sign to switch. Every time you update Jellyfin Docker container with Compose, it’s literally a two-liner. Your entire setup lives in a file you can version-control. I use Docker Compose for all my self-hosted services — including how I set up OpenClaw on my home server.

Example docker-compose.yml:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    restart: unless-stopped
    ports:
      - "8096:8096"
    volumes:
      - /opt/jellyfin/config:/config
      - /mnt/media:/media:ro

Then to update:

docker compose pull
docker compose up -d

Compose handles pulling, stopping, recreating, and restarting — all while preserving your volumes. ✅

Step 5 — Verify the Update

Don’t just assume everything is fine. Give it a quick sanity check:

# Watch the startup logs
docker logs -f jellyfin

# Confirm the container is running
docker ps | grep jellyfin

Then open http://your-server-ip:8096 → Dashboard → About and confirm the version number has changed.

If your library shows up, watch history is intact, and playback works — you’re done. 🎉

Quick success checklist:

Library is visible ✅
Watch history preserved ✅
Plugins loaded ✅
No errors in logs ✅

What Can Go Wrong (and How to Handle It)

Most updates go smoothly. But here’s what to watch for when you update Jellyfin Docker container — especially on major version jumps:

🗄️ Database schema migration — Jellyfin auto-migrates on startup. Your backup is the safety net if something goes sideways.
🔌 Plugin incompatibility — Plugins sometimes lag behind a major release. Disable them before updating, re-enable after.
📦 Config inside the container — If you skipped the check in Step 0, this is where you find out the hard way. That’s what the backup is for.
🚪 Port conflict — If something else grabbed port 8096 while Jellyfin was stopped, the container will fail to start. Check with ss -tlnp | grep 8096.

Before any major version jump, it’s worth checking the release notes on the Jellyfin GitHub releases page for breaking changes. 📋

Bonus — Automate with Watchtower

If you want updates to happen automatically in the background, Watchtower monitors your running containers and pulls new images as they’re released.

Personally, I don’t use it for Jellyfin. I prefer to check the changelog before each update — especially around major versions where plugin compatibility can be an issue. But for simpler containers where breaking changes are rare, Watchtower is great.

Wrap-up

That’s the full process I use every time I need to update Jellyfin Docker container on my home server. It takes under 5 minutes once you’ve done it a couple of times, and the backup habit will save you from a disaster eventually — trust me. 🧘

Three rules that make every update safe:

Keep your config in an external volume
Always back up before updating
Use Docker Compose — your future self will thank you

Got questions or ran into something weird? Drop it in the comments — I read everything and usually reply within a day. 👋

Logs from VahaC

How to Update Jellyfin Docker Container Without Breaking Anything