How to Update Self-Hosted Immich Server Using Docker Compose

Updating a self-hosted Immich server is a routine maintenance task, but it should be treated with the same care as any change to a system that stores personal photos and videos. Immich is under active development, and updates often bring important bug fixes, performance improvements, security patches, and database changes. If you run Immich with Docker Compose, the update process is straightforward, provided you prepare properly, back up your data, and verify the result after the containers restart.

TLDR: Before updating Immich, read the release notes, back up your database and upload library, and confirm that your Docker Compose files are current. Then pull the new images, restart the stack with Docker Compose, and watch the logs for migration or startup issues. After the update, test the web interface, mobile app access, uploads, thumbnails, search, and background jobs before considering the update complete.

Why Immich Updates Require Care

Immich is not just a simple web application. A typical self-hosted installation includes several services, such as the Immich server, microservices, machine learning container, Redis, PostgreSQL, and sometimes reverse proxy or storage-related components. Because these services work together, an update can affect more than one container.

Most Immich updates are smooth when you follow the official Docker Compose method. However, some releases include breaking changes, configuration updates, database migrations, or changes to required environment variables. Skipping release notes or updating blindly can lead to avoidable downtime.

For that reason, the safest approach is to treat every update as a controlled operation: prepare, back up, update, verify, and document what changed.

Before You Begin: Check Your Current Setup

Start by connecting to the server where Immich is installed. This is usually done over SSH. Move into the directory that contains your docker-compose.yml file and your Immich .env file.

cd /path/to/immich

Check the running containers:

docker compose ps

Confirm that the services are healthy before updating. If Immich is already failing, updating may make troubleshooting harder. In that situation, review the logs first:

docker compose logs --tail=100

You should also identify which Immich version you are currently running. Depending on your configuration, the version may be defined in the .env file as IMMICH_VERSION, or your Compose file may directly reference an image tag.

grep IMMICH_VERSION .env

If you are using release or a specific version tag, make a note of it. If you are using latest, consider changing to explicit version tags in the future. Pinning versions gives you better control and makes rollback easier.

Read the Official Release Notes

Before changing anything, read the Immich release notes for the version you plan to install. This is one of the most important steps. The release notes may mention required Compose changes, database migration behavior, changes to environment variables, removed features, or known issues.

Pay special attention to:

• Breaking changes that require manual action.
• Database migration notes, especially for major updates.
• Docker Compose changes involving services, volumes, or image names.
• Mobile app compatibility, because the server and app may need compatible versions.
• Storage and library changes that could affect external libraries or upload locations.

Do not assume that every update is identical. Immich is improving quickly, and the safest administrators are the ones who read before they restart.

Create a Reliable Backup

A backup is not optional when updating a photo management system. Your Immich instance holds metadata, thumbnails, albums, user accounts, facial recognition data, and references to your uploaded files. The database is especially important because it stores the relationships between your media and Immich’s application data.

At minimum, back up the following:

• PostgreSQL database, usually running as the Immich database container.
• Upload library, where original photos and videos are stored.
• Configuration files, including docker-compose.yml and .env.
• Custom reverse proxy configuration, if applicable.

A typical database backup command may look like this, though your database service name, username, and database name may differ:

docker compose exec database pg_dump -U postgres immich > immich_database_backup.sql

If your Compose file uses a different database container name, replace database with the correct service name. You can view service names with:

docker compose ps

Next, back up your upload directory. For example:

rsync -a /path/to/immich/upload/ /path/to/backup/immich-upload/

Also copy your Compose and environment files:

cp docker-compose.yml docker-compose.yml.bak
cp .env .env.bak

Important: A backup is only trustworthy if you know where it is stored and you are reasonably confident it can be restored. If this Immich instance is important to you, periodically test restores on a separate machine or temporary environment.

Update the Docker Compose File if Needed

Immich installations created from older templates may need changes to the Compose file. Compare your current docker-compose.yml with the current official example from the Immich documentation. Do not replace your file blindly, because your paths, ports, volumes, or reverse proxy integration may be customized.

Instead, compare carefully and update only what is necessary. Look for changes involving:

• Image names and tags.
• New or removed services.
• Volume mappings.
• Health checks.
• Environment variable names.
• Machine learning service configuration.

If you use a .env file to control the Immich version, update the version value there:

IMMICH_VERSION=v1.x.x

Replace v1.x.x with the version you intend to install. Using a clear version tag is preferable for production-like self-hosted systems because it prevents unexpected upgrades whenever images are pulled.

Pull the New Immich Docker Images

After you have reviewed the release notes, made backups, and updated configuration files if needed, pull the new images:

docker compose pull

This command downloads the updated container images defined in your Compose file. It does not, by itself, recreate your running containers. If the pull fails, do not continue until you understand why. Common causes include network problems, an invalid image tag, or authentication/rate-limit issues with the container registry.

Once the images are downloaded successfully, you are ready to restart the stack.

Restart Immich with Docker Compose

The standard update command is:

docker compose up -d

Docker Compose will recreate containers whose images or configuration have changed while keeping named volumes intact. In many cases, this is enough. However, some administrators prefer a more explicit restart sequence:

docker compose down
docker compose up -d

This stops and removes the containers, then starts them again from the updated images. It should not remove named volumes unless you add destructive flags such as -v. Do not use docker compose down -v unless you fully understand the consequences, because it can remove volumes, including database storage, depending on your configuration.

After starting the stack, immediately check container status:

docker compose ps

Then watch the logs:

docker compose logs -f

During startup, Immich may run database migrations automatically. This is normal. Do not interrupt the process unless it is clearly stuck or repeatedly failing. Database migrations may take longer on large libraries or slower hardware.

Verify the Update

Once the containers are running, open the Immich web interface in your browser. Log in and confirm that the expected version is shown. Then perform practical checks, not just a visual inspection.

Verify the following:

• The web interface loads without errors.
• Existing photos and videos are visible.
• Albums and shared links appear correctly.
• New uploads work from the web interface or mobile app.
• Thumbnails and previews are generated.
• Search, metadata, and timeline navigation behave normally.
• Background jobs are processing successfully.
• The mobile app can connect and sync.

If you use a reverse proxy such as Nginx Proxy Manager, Traefik, Caddy, or Nginx, also confirm that HTTPS access still works and that upload size limits have not become a problem. Large video uploads are especially useful for testing proxy configuration.

Clean Up Old Docker Images

After you confirm the update is successful, you may remove unused Docker images to reclaim disk space:

docker image prune

For a more aggressive cleanup, Docker provides additional prune commands, but be careful on servers that run multiple services. Avoid deleting volumes unless you are certain they are not needed.

A safe habit is to wait a few days before pruning aggressively. Keeping the previous image temporarily may make rollback easier if you discover a delayed problem.

How to Roll Back if Something Goes Wrong

If the update fails, stay calm and avoid making random changes. First, read the logs:

docker compose logs --tail=200

If the problem is a simple configuration mistake, correct it and restart:

docker compose up -d

If you need to roll back to the previous Immich version, change the IMMICH_VERSION value in your .env file back to the earlier version, then run:

docker compose pull
docker compose up -d

However, rollback can be complicated if the newer version already performed database migrations that are not backward compatible. This is why database backups are essential. In serious cases, the reliable rollback path is to stop the stack, restore the database backup, restore configuration files, restore media files if necessary, and then start the previous version.

Do not attempt a database restore over a running Immich database. Stop the stack first, or at least ensure the database is not being written to. For important installations, practice the restore process before you need it.

Recommended Maintenance Habits

A dependable Immich server is not maintained by updates alone. Good operational habits reduce risk and make future updates easier.

• Keep written notes of the version you updated from and to.
• Schedule updates when you have time to monitor the result.
• Keep regular automated backups of the database and upload library.
• Avoid unattended major upgrades unless you have tested them.
• Monitor disk space, especially if you store many videos.
• Update the mobile app when required for server compatibility.
• Review logs periodically, not only when something breaks.

If your photo library is valuable, consider keeping at least one backup outside the server itself. A second disk in the same machine is useful, but it does not protect against theft, fire, accidental deletion, or major hardware failure. Follow a sensible backup model, such as keeping local and off-site copies.

Final Checklist

Use this checklist each time you update Immich with Docker Compose:

• Confirm the current Immich version.
• Read the release notes for the target version.
• Back up the PostgreSQL database.
• Back up the upload library and configuration files.
• Update IMMICH_VERSION or image tags as needed.
• Compare your Compose file with the current official template.
• Run docker compose pull.
• Run docker compose up -d.
• Watch logs for errors and migration output.
• Test web access, mobile sync, uploads, thumbnails, and background jobs.

Updating a self-hosted Immich server with Docker Compose is usually a clean and predictable process, but the value of the data involved makes caution necessary. With release-note review, reliable backups, controlled image updates, and careful verification, you can keep Immich current while minimizing the risk of downtime or data loss. Treat the update as a small maintenance window, not a casual command, and your self-hosted photo library will be far easier to trust over the long term.