If the Immich version shown in ZimaOS is older than the upstream Immich release and the App Store does not offer an Update button, there are ways to update the containers manually—but the correct method depends on which ZimaOS Immich package you installed. The December 2025 IceWhale Community thread confirmed a simple image-tag change for the BigBear Immich package, while later replies showed that the same trick did not reliably update every other Immich package.
The community method was to open the app settings and change only the immich-server and immich-machine-learning image tags to the target release, leaving the database and Redis tabs alone. The original poster confirmed the update went smoothly, and another BigBear user later moved successfully from v2.3.1 to v2.4.1. However, current Immich documentation requires administrators to read release notes, back up the database, and account for Compose/database changes before upgrading. That means manually changing tags should not be treated as a universal “always safe” update button.
First Identify Which Immich Package You Installed
The thread contains at least two deployment paths:
- BigBear Immich: several users reported that editing the image tags in ZimaOS successfully triggered an update.
- Original/non-BigBear package: a later user reported being stuck on v2.1.0 even after trying to change the server and machine-learning versions manually.
Open the Immich app settings in ZimaOS and record the current image names, tags, volume mappings, database image, and environment variables before changing anything. Do not assume that instructions written for the BigBear definition match another App Store template.
The BigBear Tag Update That Worked in the Community
The successful community procedure was:
- On the ZimaOS dashboard, open the three-dot menu on the Immich app.
- Select Settings.
- Open the immich-machine-learning tab.
- Change its image Tag to the desired Immich release.
- Open the immich-server tab.
- Set the same release tag there.
- Leave the database and Redis tabs unchanged unless the release notes explicitly require a database/container change.
- Save the configuration and let ZimaOS recreate/pull the affected containers.
At the time of the original reply, the example tag was:
v2.3.1That version is historical. Another user later updated to v2.4.1, and an April 2026 reply mentioned v2.7.4. Do not copy any of those old version numbers today. Choose a target version only after checking the current Immich release notes and your upgrade path.
What the Original Poster Confirmed
After receiving the BigBear tag instructions, MikeFrizz replied that the tip was very helpful and that the update completed smoothly. This is the strongest confirmed result in the source thread.
That confirmation supports the method for the package and version context used by the original poster. It does not prove that manually editing two tags is sufficient for every future Immich major version or every ZimaOS package.
Do Not Assume the “latest” Tag Will Solve the Problem
One user changed the tag to latest, but ZimaOS repeatedly returned to the previously installed version. The thread then contains guesses such as trying release, but there is no source-confirmed universal fix based on those generic tag names.
Current Immich documentation uses an explicit version variable and supports major-version metatags in its own Docker Compose workflow. For a packaged ZimaOS app, use the tag format that the package definition and upstream image actually support. Avoid inventing tags because a label sounds plausible.
Back Up Immich Before Changing Versions
Current Immich documentation explicitly recommends backing up the database before upgrades that can involve migrations. Your photos and videos also need an independent backup strategy; a database backup does not replace the media library itself.
Use the current Immich backup and restore guide before a manual version jump.
At minimum, preserve:
- the Immich database backup;
- the media library/upload data;
- the current ZimaOS app configuration and volume mappings;
- the current image tags;
- and any environment variables or custom storage locations.
Read the Immich Release Notes Before Every Version Jump
Current Immich upgrade documentation says administrators should check release notes for breaking changes before updating. The normal upstream Docker Compose process is:
docker compose pull && docker compose up -dbut only after the Compose definition and version variables are appropriate for the target release.
See the current Immich upgrading guide.
This matters for ZimaOS because a packaged app can lag not only in image tags but also in its Compose-equivalent definition. A newer immich-server image may expect database, environment, health-check, or volume changes that an older package does not contain.
Keep Immich Server and Machine Learning Versions Compatible
The community specifically changed the tags for both immich-server and immich-machine-learning. Current Immich documentation likewise warns that version mismatches between the main server and machine-learning components can cause bugs or instability.
Do not update only one of the two because it happened to show an available image first. Treat them as one coordinated application version unless the current release documentation explicitly says otherwise.
Do Not Randomly Change the Database Container Tag
The community advice to leave the database tab alone was sensible for the exact BigBear minor updates discussed there. Immich's PostgreSQL layer has its own migrations and has changed over time, including migration from older vector extensions to VectorChord.
- Do not bump the database image merely to make all tags look numerically similar.
- Do not assume the database image must never change; if current Immich release notes require a database/Compose migration, follow that documented migration instead.
What If the Original ZimaOS Immich App Stays on an Old Version?
A March 2026 reply said the user was not running the BigBear App Store version and remained stuck on Immich v2.1.0 even after manually trying to update the machine-learning and server images. The thread does not contain a confirmed resolution for that user's original-package deployment.
That is an important boundary: if manually changing the image tags does not update the app, stop repeating the same operation. Compare the package's current container definition with Immich's current Compose requirements and consider migrating to a maintained ZimaOS package only after backing up and confirming the data paths.
Do not uninstall a working Immich package before you know where its database and media volumes are stored.
Why Community Users Suggested the BigBear Immich Package
The first reply recommended the BigBear Immich app because it was usually kept closer to upstream releases. The later successful tag-edit instructions were also explicitly tested on BigBear.
This does not make “reinstall BigBear” a safe one-click migration path for an existing library. A fresh package can use different volume names, data directories, database images, or environment variables. Treat package migration as a separate operation from upgrading an existing stack.
Be Careful with Automatic Container Updaters
An April 2026 community reply suggested Tugtainer as an easier alternative to Watchtower for checking and automatically updating containers. That suggestion may be convenient for stateless services, but Immich is a stateful multi-container application with a PostgreSQL database and documented breaking-change upgrade paths.
For Immich, automatic image replacement without reading release notes can be risky. Current Immich documentation explicitly tells administrators to account for breaking changes before upgrades. If you use an automatic container updater at all, prefer notification/manual approval for Immich rather than blindly updating every new tag.
Safer ZimaOS Immich Update Workflow
- Record whether the installed package is BigBear or another Immich definition.
- Record the current server, machine-learning, database, and Redis images/tags.
- Back up the Immich database and important media.
- Read the upstream release notes for every breaking-change boundary between your current and target versions.
- Confirm whether the target version requires Compose, database, environment-variable, or storage changes.
- For a compatible BigBear minor update, change the server and machine-learning tags together as the community did.
- Leave database/Redis images unchanged unless the documented upgrade path specifically requires a change.
- Save the app settings and watch the container logs while the new images start.
- Verify the Immich Web UI version, uploads, thumbnails, machine learning, and existing library before deleting old images.
- If the package immediately rolls back or remains on the old version, inspect the package definition rather than repeatedly forcing tags.
What to Verify After an Immich Update
- The Web UI loads and reports the intended server version.
- The mobile app can connect and is compatible with the server major version.
- Existing photos and videos open correctly.
- New uploads complete successfully.
- Thumbnail and transcoding jobs run.
- Machine-learning features start without version mismatch errors.
- The PostgreSQL container remains healthy.
Current Immich documentation notes that downgrading is not a supported recovery strategy. A backup is safer than assuming you can simply change the tag back after a database migration.
ZimaOS Immich Update FAQ
Can I update Immich by changing the ZimaOS image tags?
Yes for some package/version combinations. The original poster and another BigBear user confirmed that changing both the server and machine-learning tags worked. The thread also contains a non-BigBear user for whom the method did not solve the outdated installation.
Which Immich tags should I change?
In the confirmed BigBear community method, the immich-server and immich-machine-learning tags were changed together. Do not copy the old v2.3.1, v2.4.1, or v2.7.4 examples as current target versions.
Should I use latest?
Not as a universal fix. A user in the thread reported that latest did not stick. Use the versioning scheme supported by your actual package and current Immich guidance.
Can I just run docker pull?
Pulling a new image alone does not recreate the running container or apply Compose changes. Upstream Immich uses docker compose pull && docker compose up -d after the configuration is prepared for the target release.
Should Tugtainer or Watchtower automatically update Immich?
Automatic updates can skip the release-note and migration review that Immich explicitly recommends. For a stateful application with a database, notification and controlled manual upgrades are safer than blind automatic replacement.
Do I need a backup before an Immich update?
Yes. Immich's current upgrade and backup documentation recommends protecting the database before upgrades, and you should separately protect irreplaceable media.
