How to Update Immich Server Without Breaking Database or Storage

Updating an Immich server should be treated as a careful maintenance task, not a casual restart. Immich is a fast-moving self-hosted photo and video management platform, and its components often depend on specific versions of the database, Redis, machine learning service, and storage paths. A successful update protects the PostgreSQL database, preserves the upload library, and keeps Docker configuration consistent.

Why Immich Updates Need Care

Immich stores irreplaceable media, metadata, thumbnails, user accounts, albums, facial recognition data, and background job records. While the original photos and videos are usually stored in the upload directory or an external library path, the database contains the structure that makes the library searchable and usable. If the database is damaged, replaced, or mismatched with the application version, the server may start incorrectly or display missing assets.

Most Immich installations run through Docker Compose. This makes updating convenient, but it can also create a false sense of safety. Pulling the newest images and restarting containers may work for minor updates, but it can cause trouble if the release includes breaking changes, required environment variables, or database migration changes. The responsible administrator updates in a controlled sequence.

Step 1: Read the Release Notes Before Updating

The first step is to review the official Immich release notes for the target version. Immich evolves quickly, and some updates include important migration warnings. The administrator should look for:

• Breaking changes that require edits to docker-compose.yml or .env.
• Database migration notes that may affect PostgreSQL compatibility.
• Required image changes for the server, machine learning, Redis, or database containers.
• Storage path changes that could affect uploads, external libraries, or thumbnails.
• Recommended upgrade paths, especially when skipping several versions.

If the server is many releases behind, the administrator should avoid jumping blindly to the newest version. Some projects handle multi-version migrations well, but a cautious operator checks whether intermediate upgrades are recommended. This is especially important for production family archives or professional media collections.

Step 2: Verify the Current Setup

Before changing anything, the administrator should document the current environment. This includes the Immich version, Docker Compose file, environment file, storage mounts, database container name, and physical location of media files. A copy of the current docker-compose.yml and .env file should be saved somewhere outside the Immich application directory.

It is also important to identify where the database and media are stored. A typical Docker Compose setup may have named volumes for PostgreSQL and Redis, plus bind mounts for uploads. The upload directory is especially critical. If a container is recreated with the wrong mount path, Immich may appear empty even though the files still exist on disk.

A careful administrator checks permissions as well. The user and group IDs used by the container must still have access to media folders after the update. Permission problems can appear as broken thumbnails, failed uploads, missing previews, or background job errors.

Step 3: Create a Database Backup

The database backup is the most important safety step. Immich relies on PostgreSQL, and a simple copy of the database volume while the container is running is not always a reliable backup. The safer method is to use pg_dumpall or pg_dump, depending on the deployment and backup strategy.

A typical backup command may look like this, adjusted for the actual container and credentials:

docker exec -t immich_postgres pg_dumpall -c -U postgres > immich_database_backup.sql

The administrator should confirm that the backup file is not empty and is stored outside the Docker volume. Ideally, the backup should be copied to another machine, external disk, or backup location. A backup stored on the same failing drive as the server is not a complete safety net.

For more advanced setups, the administrator may back up a specific database instead of all databases. The correct approach depends on how PostgreSQL has been configured. In all cases, the backup should be created before any new container images are pulled or database migrations are allowed to run.

Step 4: Back Up Configuration and Storage

The database is not the only thing that matters. The administrator should also preserve configuration files and media storage. At minimum, the following should be backed up:

• docker-compose.yml
• .env
• Any custom reverse proxy configuration
• Any external library path configuration
• The upload directory or storage volume
• Custom scripts, cron jobs, or backup automation

The upload library may be too large for a quick full backup before every update, but it should already be protected by a regular backup plan. If no media backup exists, the administrator should pause and create one before updating. Immich is not a backup by itself; it is an application that organizes media. The media files still require independent protection.

Step 5: Stop Immich Cleanly

Before updating, the administrator should stop the Immich stack cleanly. This prevents uploads, thumbnail generation, and database writes from happening during the update process. In most Docker Compose installations, the command is:

docker compose down

Some administrators prefer to stop only the application containers while keeping the database running for backup operations. That can be acceptable, but the essential point is that no active Immich process should be writing to the database during a critical backup or version change.

Step 6: Update Docker Compose and Environment Files

After backups are complete, the administrator should apply any required changes from the release notes. This may include new variables in the .env file, changed image names, updated health checks, or modified service definitions. The operator should not simply overwrite a customized Compose file without comparing changes.

A good practice is to keep a clean copy of the official example configuration and compare it with the existing file. This helps reveal new services, deprecated options, and renamed variables. If the installation uses a reverse proxy, hardware acceleration, external libraries, or custom storage paths, those customizations must be preserved carefully.

Step 7: Pull New Images and Start the Stack

Once configuration has been reviewed, the administrator can pull the updated images:

docker compose pull

Then the stack can be started:

docker compose up -d

At this point, the database may run migrations automatically. The administrator should not interrupt this process unless there is a clear failure. Stopping containers during a migration can create a more complicated recovery situation. The logs should be watched closely:

docker compose logs -f

The server logs may show migration progress, connection errors, missing variables, or permission problems. If the logs show repeated crashes, the operator should avoid repeatedly recreating containers without understanding the cause. The safer option is to stop, review logs, compare release notes, and restore from backup if necessary.

Step 8: Check Database and Storage Health

After the containers start, the administrator should verify that the database is connected and the storage paths are correct. A healthy update usually shows the web interface loading normally, users remaining present, albums intact, and assets visible. If thumbnails are temporarily missing, background jobs may need time to regenerate or catch up.

Important checks include:

1. Logging in with an existing user account.
2. Opening several older photos and videos.
3. Uploading a new test image.
4. Checking that thumbnails and previews generate properly.
5. Confirming that external libraries still scan correctly.
6. Reviewing job queues and server logs for recurring errors.

If Immich reports missing files, the administrator should check volume mappings before assuming data loss. In many cases, the files are still present but the container is looking in the wrong location. Path consistency is crucial. A changed mount path can break references between the database and the filesystem.

Step 9: Avoid Common Mistakes

The most common update mistakes are preventable. One major mistake is deleting Docker volumes without understanding what they contain. A named PostgreSQL volume may hold the entire database. Removing it can erase accounts, albums, metadata, and asset records. Another mistake is changing upload paths casually. Immich expects stored assets to remain where the database says they are.

Administrators should also avoid using the latest tag without awareness. While convenient, it can introduce unexpected changes during routine pulls. Some operators prefer pinning a specific Immich version and updating intentionally after reviewing the release notes. This reduces surprise upgrades.

Another risky habit is skipping backups because a previous update worked. Past success does not protect against future migrations, disk failures, human error, or incompatible configuration changes. A backup routine should be boring, repeatable, and tested.

Step 10: Have a Rollback Plan

A rollback plan should exist before the update begins. If the update fails before database migrations, rolling back may be as simple as restoring the previous Compose file and pulling the older images. If migrations have already changed the database, rolling back the application alone may not work. In that case, the administrator may need to restore the pre-update database backup.

A safe rollback generally involves stopping the stack, restoring the previous configuration, restoring the database backup if needed, and starting the older version. The operator should also ensure that the media storage was not altered during the failed update. Since original media files are usually separate from the database, they may remain safe, but this should still be verified.

Best Practices for Long-Term Maintenance

Immich maintenance becomes easier when the server follows predictable practices. The administrator should schedule updates during low-use periods, avoid updating while large imports are running, and keep a written maintenance log. This log can record the previous version, new version, backup file name, date, and any configuration changes.

Regular health checks are also useful. Disk space should be monitored because Immich can generate thumbnails, encoded videos, and machine learning data. If the disk fills during an update or migration, failures may occur. Database backups should be tested occasionally by restoring them to a separate environment. A backup that has never been tested is only an assumption.

For important libraries, a staging server can be valuable. The administrator can copy the configuration and database backup to a test environment, perform the update there, and confirm that migrations succeed before touching the main server. This is more work, but it greatly reduces risk for large or sensitive collections.

FAQ

Should the administrator back up Immich before every update?

Yes. At minimum, the PostgreSQL database and configuration files should be backed up before every update. Media storage should also be covered by a regular backup plan.

Can Immich be updated by only running docker compose pull and docker compose up -d?

Sometimes, but it is not the safest habit. The administrator should first read the release notes, check for breaking changes, and create backups before pulling and starting new containers.

What is the biggest risk during an Immich update?

The biggest risk is damaging or losing the database, especially if volumes are deleted or migrations fail without a backup. Incorrect storage mounts are another common cause of apparent data loss.

What should be done if photos disappear after an update?

The administrator should first check Docker volume mappings and storage paths. If the files still exist on disk, Immich may simply be looking in the wrong location. Logs and configuration files should be reviewed before restoring backups.

Is Immich a replacement for a real backup system?

No. Immich organizes and displays photos and videos, but the media files, database, and configuration still need independent backups.

Should old Docker volumes be removed after updating?

Not immediately. Docker volumes may contain critical database or application data. The administrator should identify every volume and confirm it is no longer needed before deleting anything.

How can an administrator reduce update problems in the future?

The best approach is to maintain regular backups, pin known versions when appropriate, read release notes, monitor disk space, and test major upgrades in a separate environment whenever possible.