How to Update Immich Server Step-by-Step (Docker Guide)
Posted inBlog

How to Update Immich Server Step-by-Step (Docker Guide)

Updating an Immich Server with Docker can feel scary. Your photos live there. Your videos live there. Your memories live there. But do not worry. With a calm plan, a backup, and a few commands, you can update Immich without turning your server into digital soup.

TLDR: Make a backup first. Read the Immich release notes before you update, because some versions need extra steps. Then run docker compose pull and docker compose up -d from your Immich folder. After that, check the logs, test the web app, and make sure your mobile app still connects.

Before You Start: The Tiny Safety Talk

Immich is wonderful. It is also moving fast. New versions can bring new features, database changes, and sometimes breaking changes. That is normal for a young and active project.

So here is the golden rule:

Never update Immich without a backup.

Say it with me. Backup first. Party later.

You should also avoid automatic updates for Immich. Tools that auto-update Docker containers sound helpful. But with Immich, they can cause trouble. A surprise update at 3 a.m. is not cute. It is a goblin with a keyboard.

Do the update yourself. On purpose. With snacks.

What You Need

Before updating, make sure you have these things:

  • SSH access to your server.
  • Your Immich Docker Compose folder.
  • A working docker compose command.
  • Enough disk space for backups.
  • A few calm minutes.

Your Immich folder is usually the place where these files live:

  • docker-compose.yml
  • .env
  • Maybe a library or upload folder

If you do not know where it is, search for it:

find / -name "docker-compose.yml" 2>/dev/null

Or check common places like:

/opt/immich
/home/YOURUSER/immich
/docker/immich

Step 1: Connect to Your Server

Open your terminal. Connect with SSH:

ssh youruser@your-server-ip

Now go to your Immich folder:

cd /path/to/immich

Replace the path with your real folder. For example:

cd /opt/immich

Check that you are in the right place:

ls

You should see your Compose file. If you see nothing useful, you may be in the wrong kitchen. Go find the right kitchen before cooking.

Step 2: Check Your Current Immich Version

It helps to know where you are starting. Run:

docker compose ps

You can also inspect the running images:

docker images | grep immich

Write the version down if you want. It may help if you need to roll back.

Also open the Immich web app in your browser. Check that it works before you update. This sounds silly. It is not. If something is broken before the update, the update may not be the villain.

Step 3: Read the Release Notes

This step is boring. It is also important.

Go to the Immich release page and check the versions between your current version and the newest version. Look for words like:

  • Breaking change
  • Migration
  • Manual step required
  • Docker Compose change
  • Environment variable change

If the release notes tell you to change your Compose file, do it. If they tell you to update your .env file, do it. If they tell you to sacrifice a USB cable to the server spirits, maybe do not do that. But read carefully.

Step 4: Back Up the Database

The database is the brain of Immich. It stores users, albums, tags, jobs, metadata, and more. You want a copy of that brain before surgery.

Create a backup folder:

mkdir -p backup

Now back up the database. Many Immich Docker setups use a service named database. Many use PostgreSQL with the user postgres. If your setup uses a different username, check your .env file.

docker compose exec -T database pg_dumpall --clean --if-exists --username=postgres > backup/immich-database-backup.sql

If that command works, you should now have a database backup file.

Check it:

ls -lh backup

You should see a file with a size greater than zero. A zero-byte backup is not a backup. It is a tiny paper hat.

Step 5: Back Up Your Photos and Upload Folder

Your media files matter most. The database is important, but your photos and videos are the treasure chest.

Your upload location is usually set in the .env file. Check it:

cat .env

Look for something like:

UPLOAD_LOCATION=./library

Or:

UPLOAD_LOCATION=/mnt/photos/immich

Back up that folder to another drive, NAS, or safe location. For example:

rsync -avh /mnt/photos/immich/ /mnt/backup/immich-library/

Change the paths. Do not copy the command blindly. The server does not know your life.

If your library is huge, this step can take time. That is fine. Let it run. Make tea. Touch grass. Brag to nobody that you are being responsible.

Image not found in postmeta

Step 6: Stop Immich Cleanly

This is optional for many updates, because Docker can replace containers while keeping volumes. Still, stopping cleanly can make things feel safer.

docker compose down

This stops the containers. It does not delete your volumes. It does not delete your photos. It just tells the containers to sit down for a moment.

Important: Do not run commands like docker compose down -v unless you know exactly what you are doing. The -v flag removes volumes. That can delete important data. It is the shiny red button. Do not poke it.

Step 7: Update Your Docker Compose Files

Immich often provides an official Docker Compose file and an example .env file. Sometimes these files change between versions.

Compare your current files with the latest official example. Look for new services, changed image names, new variables, or removed settings.

Your images may use a version tag like this:

image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}

And your .env file may contain:

IMMICH_VERSION=release

Using release means Docker pulls the latest stable release. Some people prefer pinning a specific version, like:

IMMICH_VERSION=v1.123.0

Pinning gives you more control. Using release is easier. Pick the style that matches your comfort level.

If you are updating across many versions, consider doing it in smaller jumps. Big jumps can work. But small jumps are easier to debug. Think stairs, not trampoline.

Step 8: Pull the New Images

Now the fun begins. Pull the latest images:

docker compose pull

Docker will download updated Immich images. It may also download updated database, Redis, or machine learning images if they changed.

If the command fails, read the error. Common causes include:

  • No internet connection.
  • Wrong image name.
  • Old Compose file.
  • Disk space is full.
  • Docker login or registry issue.

Check disk space with:

df -h

If your server is full, clear space before continuing. Docker images are chunky little beasts.

Step 9: Start Immich Again

Start the updated containers:

docker compose up -d

The -d means detached mode. In human words, it runs in the background.

Now check what is running:

docker compose ps

You want to see your Immich services as healthy or running. Some services may take a little time. The database may run migrations. The server may stretch its legs. Be patient.

Step 10: Watch the Logs

Logs are your server’s diary. Read them.

docker compose logs -f

If that is too much noise, check the server only:

docker compose logs -f immich-server

Depending on your Compose file, the service name may be different. You can see service names with:

docker compose ps

Watch for errors. A few warnings may be normal. Repeated crash loops are not normal. If a container keeps restarting, something needs attention.

To stop watching logs, press:

Ctrl + C

Step 11: Open Immich in Your Browser

Now visit your Immich web address.

Log in. Check the main timeline. Open an album. Search for a photo. Play a video. If you use face recognition or machine learning, check that features load.

Also open the Immich mobile app. If needed, update the app from your app store. Sometimes server and mobile versions need to stay close together. If your phone app complains, update it too.

Upload one small test photo. Make sure it appears. Then delete it if you want. This is your little “hello world” for photo land.

Step 12: Let Background Jobs Finish

After an update, Immich may run background tasks. It may reprocess metadata. It may update thumbnails. It may work on search, faces, or video data.

Do not panic if CPU usage rises. Your server may just be doing chores. Servers also have laundry.

You can check containers with:

docker stats

If everything is responsive, let it work. If it is unusable for a long time, check logs again.

Step 13: Clean Up Old Docker Images

When you are happy, you can remove old unused images. This saves disk space.

docker image prune

Docker will ask for confirmation. Read the message. If it only removes dangling images, it is usually safe.

For a stronger cleanup, you may see people use:

docker system prune

Be careful with that. It removes more things. Do not run big cleanup commands unless you understand what they remove.

What If Something Breaks?

First, breathe. Most update issues are fixable.

Check logs:

docker compose logs

Check service status:

docker compose ps

Check disk space:

df -h

Check your Compose file and .env file. A missing environment variable can cause chaos. A wrong path can break uploads. A typo can defeat a mighty server. Computers are dramatic like that.

If you pinned a version, you can roll back by setting IMMICH_VERSION to the old version, then running:

docker compose pull
docker compose up -d

If the database was migrated, rollback may be harder. That is why the backup matters. For serious problems, stop and read the release notes again. Then check the Immich community or documentation for version-specific fixes.

Simple Update Command Checklist

Here is the quick version for future you. Future you is busy. Be kind to them.

  1. Go to the Immich folder.
  2. Read the release notes.
  3. Back up the database.
  4. Back up the photo library.
  5. Update Compose or .env if needed.
  6. Pull new images.
  7. Start containers.
  8. Check logs.
  9. Test web and mobile apps.

The core commands look like this:

cd /path/to/immich

mkdir -p backup

docker compose exec -T database pg_dumpall --clean --if-exists --username=postgres > backup/immich-database-backup.sql

docker compose pull

docker compose up -d

docker compose logs -f

Final Thoughts

Updating Immich with Docker is not magic. It is a recipe. Backup. Read. Pull. Start. Test. That is the whole sandwich.

The most important part is not the Docker command. It is the habit. Read release notes. Keep backups. Avoid surprise automatic updates. Test after every change.

Do that, and your Immich server will stay fresh, fast, and ready for new memories. Your photos deserve a safe home. Your server deserves a careful admin. And you deserve a tiny victory dance when the update works.