9 June 2026

Best Commands to Update Immich Server Using CLI and Docker

Updating an Immich server from the command line is usually straightforward, but it should never be treated as a careless routine. Immich is an actively developed self hosted photo and video management platform, and updates may include database migrations, container changes, dependency changes, or configuration adjustments. The safest approach is to use Docker Compose, verify your current setup, create a reliable backup, pull the correct images, and then restart the stack in a controlled way.

TLDR: Before updating Immich, always back up your database and confirm your current Docker Compose configuration. The most common update workflow is to edit your .env file if needed, run docker compose pull, then run docker compose up -d. After the update, check container status and logs carefully. For production or family photo libraries, avoid blindly using latest unless you understand the risks.

Before You Update: Know What You Are Running

The first command you should run is not an update command. It is a verification command. Before changing anything, confirm where your Immich files are stored, which containers are running, and which version you are currently using. Most Immich Docker installations are managed from a directory containing files such as docker-compose.yml and .env.

cd /path/to/immich
docker compose ps

This command displays the containers managed by Docker Compose, including services such as the Immich server, machine learning container, Redis, and PostgreSQL database. If this command fails, you may be in the wrong directory, or your system may be using the older docker-compose command instead of the modern docker compose plugin.

You can also confirm the image versions currently in use:

docker compose images

This is useful because it gives you a record of what was running before the update. If you need to troubleshoot later, this information can help identify whether a new image introduced an issue.

Check the Immich Version Setting

Immich deployments commonly use an environment variable such as IMMICH_VERSION in the .env file. Depending on your installation method, it may be set to a specific release version or to release.

cat .env

Look for a line similar to this:

IMMICH_VERSION=release

Using release generally tracks the current stable release. Pinning to a specific version, such as v1.123.0, gives you more control and can be preferable on critical systems. The best choice depends on your tolerance for update risk. For a personal server used by several family members, pinning versions and updating deliberately is often a more conservative approach.

If you decide to change the version, edit the file carefully:

nano .env

After saving changes, Docker Compose will use the updated variable the next time you pull and recreate containers.

Read the Release Notes First

A serious update process includes checking release notes before running commands. Immich updates may occasionally require manual steps, configuration changes, or awareness of breaking changes. This is especially important if you are skipping many versions at once.

As a rule, you should look for information about:

• Database migrations that may take time on large libraries.
• Changes to Docker Compose files or environment variables.
• Deprecated settings that should be removed or renamed.
• Machine learning service changes that may affect hardware acceleration.
• Known issues reported for the target release.

Many update failures are not caused by the command itself, but by skipping this review step. A cautious administrator checks the expected changes before applying them.

Back Up the Immich Database

The most important command in this process is the backup command. Immich stores metadata, users, albums, library information, and other important application data in PostgreSQL. Your uploaded photos and videos are important, but the database is also critical because it describes how Immich understands and organizes that content.

If your PostgreSQL container is named immich_postgres, you can create a backup using pg_dumpall like this:

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

Some installations may use a different database username or container name. Run this command to confirm service names:

docker compose ps

If your database service is called database in Compose, you may need:

docker compose exec database pg_dumpall -c -U postgres > immich_database_backup.sql

After creating the backup, verify that the file exists and is not empty:

ls -lh immich_database_backup.sql

Do not store your only backup inside the same directory and disk that you are about to modify. Copy it to another machine, cloud storage, NAS, or external drive. For larger installations, also back up your upload library and configuration files.

cp docker-compose.yml docker-compose.yml.backup
cp .env .env.backup

Image not found in postmeta

Best Basic Command to Update Immich

For a standard Docker Compose installation, the core update commands are simple:

docker compose pull
docker compose up -d

The first command downloads newer images according to your Compose file and version variables. The second command recreates containers where needed and starts the stack in detached mode. This is the most common and recommended update pattern for many Immich installations.

If your system still uses the legacy Compose binary, the equivalent commands are:

docker-compose pull
docker-compose up -d

However, modern Docker installations generally use docker compose without the hyphen. If possible, prefer the newer syntax.

Update Immich with a Controlled Restart

Some administrators prefer to stop the stack first, then pull and start again. This can make the update sequence clearer, especially when working on a server with limited resources.

docker compose down
docker compose pull
docker compose up -d

This approach causes more obvious downtime because the services are stopped before new images are downloaded. For home use, that may be acceptable. For shared or remote access, you may prefer pulling images first, then recreating containers:

docker compose pull
docker compose up -d

This typically keeps downtime shorter because image downloads happen while the current stack may still be running.

Update Only Immich Services

In some cases, you may not want to pull every image. For example, PostgreSQL and Redis may not need frequent changes unless the Compose file or release notes indicate otherwise. You can pull specific services by name:

docker compose pull immich-server immich-machine-learning
docker compose up -d immich-server immich-machine-learning

Service names vary by Compose file, so confirm them first:

docker compose config --services

This command is particularly useful because it shows the exact service names Docker Compose recognizes. Using exact names prevents mistakes when running targeted updates.

Check Logs During and After the Update

Once containers are recreated, do not assume the update succeeded just because the command returned without an obvious error. Check the service status:

docker compose ps

Then review logs:

docker compose logs -f

To inspect only the Immich server logs, use:

docker compose logs -f immich-server

Database migrations may appear in the logs during first startup after an update. On large libraries, migrations can take time. During this period, avoid repeatedly restarting containers unless the logs clearly show a fatal error. Interrupting a migration unnecessarily can make recovery more complicated.

If the machine learning service is slow to start, check its logs separately:

docker compose logs -f immich-machine-learning

Look for repeated crash loops, missing environment variables, permission problems, or database connection errors. A healthy update should eventually show stable containers and accessible web login.

Clean Up Old Docker Images

After confirming that Immich is working correctly, you may want to remove unused Docker images to recover disk space. This is especially useful on small VPS instances or home servers with limited storage.

docker image prune

For a more aggressive cleanup of unused images, containers, networks, and build cache, use:

docker system prune

Be careful with cleanup commands. They should generally be run after you confirm the update is successful, not before. If you remove old images immediately and then discover a problem, rolling back may become less convenient.

Rollback Considerations

A rollback is easier when you have a database backup, old configuration files, and knowledge of the previous image version. If you pinned IMMICH_VERSION, you can change it back in .env and redeploy:

nano .env
docker compose pull
docker compose up -d

However, be cautious. If a newer Immich version performed database migrations, simply starting an older version may not always be safe. In that case, a true rollback may require restoring the database backup created before the update. This is why backups are not optional for responsible maintenance.

Useful One Line Update Workflow

For experienced users who have already backed up and reviewed release notes, a concise update command can be convenient:

cd /path/to/immich && docker compose pull && docker compose up -d && docker compose ps

This command changes to the Immich directory, pulls updated images, recreates containers, and prints status. It is efficient, but it should not replace the backup and verification process. A short command is helpful only when supported by good operational discipline.

Recommended Safe Update Sequence

For most users, the following sequence is a balanced and dependable way to update Immich:

1. Open the Immich directory: cd /path/to/immich
2. Check running services: docker compose ps
3. Back up the database: docker compose exec database pg_dumpall -c -U postgres > immich_database_backup.sql
4. Back up configuration: cp .env .env.backup and cp docker-compose.yml docker-compose.yml.backup
5. Pull new images: docker compose pull
6. Start updated containers: docker compose up -d
7. Check status: docker compose ps
8. Watch logs: docker compose logs -f
9. Verify in the browser: log in, open the timeline, and confirm uploads and search behave normally.

Final Advice

The best commands to update Immich are not just docker compose pull and docker compose up -d. Those are the core technical steps, but the best update process includes preparation, backup, verification, and monitoring. Immich often stores irreplaceable personal media, so the update procedure should reflect the value of that data.

Use the CLI with care, keep your Compose files organized, avoid unnecessary changes during updates, and maintain external backups. When handled seriously, Docker makes Immich updates predictable and manageable. A careful administrator can keep the server current while minimizing downtime and protecting the photo library that depends on it.