Skip to content

News

This page list news and announcements related to Immich Distribution. I will only write here if there is something new, interesting or breaking. If you like to follow my release process, see the new-version tag on GitHub.

  • 1 min read

Breaking Change in v1.137: Upgrade Required for Older Versions

Immich v1.137.0 introduces a breaking change affecting users on versions older than v1.132.0 (released May 9, 2025). If you have automatic updates enabled (default), no action is required. However, the few users running older versions must manually upgrade to an intermediate version first.

Required Action

If running a version older than v1.132.0:

  1. Upgrade to v1.136.0 first: 
    sudo snap refresh immich-distribution --revision=218
  2. Allow Immich to start successfully
  3. Then upgrade to v1.137+ normally

Check your version: snap list immich-distribution

Why This Change?

Immich removed TypeORM (#20366) requiring database schema upgrades that must be completed on versions v1.132.0-v1.136.0 before upgrading to v1.137+.

Resources

Important Notifications & Backup database

New Notification System

Immich recently introduced a notification system and an API to send these notifications. I'm going to use this to inform you of important information in the future, and this is the first time you'll see a notification like this. All notifications will have a blog post like this one that contains additional information.

Immich has moved on from pgvecto.rs to VectorChord. That's a new vector extension to Postgres that is replacing it. At the moment Immich supports both but the old one will be deprecated in a future release.

Migration from pgvecto.rs to VectorChord should be automatic and safe, but there's always a risk. I have intentionally waited for about two months to make sure that code stabilized before pushing out this release, but to be on the safe side, I recommend highly that you make sure you have working backup.

There are two backup systems in Immich Distribution. The one provided by us and the one provided by the upstream Immich project. Please enable at least one of these backup options so it's possible to restore your installation if anything breaks.

You will find backups for Immich Distribution in /var/snap/immich-distribution/common/backups/ and you will find backups made by the builtin feature in Immich in /var/snap/immich-distribution/common/upload/backups/. You can also run the following command to list all backups: immich-distribution.backup -l.

As usual, I will always test everything to make sure this is a smooth, automatic zero care upgrade.

  • 1 min read

Automatic API Key for System Administration

Starting with revision 213, Immich Distribution automatically creates an internal API key for system administration tasks. This change has been in beta and is now released to stable.

What's New

The manager service automatically creates an API key named immich-distribution for the first admin user. This key is used exclusively for internal operations and enables the system to use official Immich APIs instead of direct database access for automated tasks.

What You Need to Know

  • No action required - The key is created and managed automatically
  • Internal use only - Not accessible to users, only for system operations
  • Maintenance schedule - Checked and recreated if needed twice daily (06:00 and 18:00)

This change improves reliability and follows best practices by using official APIs over custom solutions for internal functionality, internal scripts, and internal processes.

We have also extended the immich-admin CLI command with an extension to allow us to create this API key from inside the snap package. For more information about this extension, see the Immich Admin Extensions documentation.

If you notice any unexpected behavior, please report it on the GitHub repository.

  • 2 min read

Stuck at v1.133.1

If you find yourself stuck at version 1.133.1 with one of the following error messages, please continue reading.

error: cannot perform the following tasks:
- Run pre-refresh hook of "immich-distribution" snap if present (run hook "pre-refresh": 
-----
/snap/immich-distribution/195/snap/hooks/pre-refresh: line 9: /snap/immich-distribution/195/backup: No such file or directory
Failed to create and validate database backup during pre-refresh.
-----)

error: cannot perform the following tasks:
- Run pre-refresh hook of "immich-distribution" snap if present (run hook "pre-refresh": 
-----
Creating database backup: /var/snap/immich-distribution/common/backups/immich_database_v1.133.1_pgvectors.sql.xz

<exceeded maximum runtime of 10m0s>
-----)

To resolve this, follow these steps:

  1. Disable the hook by executing: touch /var/snap/immich-distribution/common/no-pre-refresh-hook
  2. Update as you normally would (for example, snap refresh).
  3. Restore the hook by executing: rm /var/snap/immich-distribution/common/no-pre-refresh-hook

Only users on the unstable edge, beta, or candidate channels need to perform these steps. This bug was identified during testing before it affected the stable channel.

Technical background

In preparation for the upcoming migration from pgvecto.rs to VectorChord, a database backup step was added to the pre-refresh hook. This hook is designed to back up the database before a snap update occurs. However, a bug was introduced in the pre-refresh script in revision 195 due to an incorrect path being committed.

Although a fix was implemented in the subsequent revision, users who had already updated to revision 195 found themselves stuck. This was because the pre-refresh hook runs before the update process, causing the update to fail repeatedly due to the faulty script.

Unfortunately, there was no way to automatically push a fix for this issue to affected users. Thankfully, a mechanism to disable the hook was already in place, which is the solution employed here.

Later, during further testing, it was discovered that on some systems, the database backup process could exceed the 10-minute timeout. This scenario would trigger a similar problem, effectively blocking the update.

Given these challenges, the decision has been made to revert this pre-refresh backup feature for now.

  • 1 min read

Upcoming database changes

Immich version 1.133.0 replaces the deprecated pgvecto.rs extension with its replacement VectorChord. To ease transition, Immich will support both in parallel for a few releases.

There is also a breaking change in the API between the mobile application and the server. With this in mind, I will fast-track this release and postpone the VectorChord change to a later, separate release.

Breaking change in the mobile app

Please ensure both your mobile app and the server are updated to v1.133.0. Older versions of the Immich mobile app will not work correctly with server version v1.133.0.

Upgrading from 1.107.2 or older

Due to the automatic updates in the package format, most users are on recent versions. Snap Store metrics show that only 0.5% of users are running releases this old. If you are one of these rare users, you need to manually update to a newer intermediate release before upgrading to the most recent release.

Database backup

There are a lot of database changes, which introduces some risk. If you have not done so already, this is probably a good time to enable automatic database backups. You can either use the built in backup job (should be enabled by default), or the backup tool included in this snap.

Use immich-distribution.backup -l to list existing backups.

  • 1 min read

Release update

I took a month for this release due an unusable buggy 1.125 release with six patch releases. The database layer has been swapped out in the upstream project and with a large change like this I was in no hurry to update. I also have a lot of personal things going on, so it fit me well to take a month of while it settled down a little.

I will release 1.126 directly to stable in a few days assuming I see no issues in my testing.

  • 1 min read

Breaking change in Metrics Configuration

The upstream Immich project has changed the configuration format for metrics in the v1.119.0 release. You will be affected if you have enabled metrics-enabled and configured metrics-api-enabled, metrics-host-enabled, metrics-io-enabled or metrics-job-enabled to limit collected telemetries.

Check out the metrics documentation for more information.

  • 1 min read

Breaking change in OAuth

Upstream Immich has this message attached to the release page for Immich 1.113. If you use OAuth with the mobile application you need to update your OAuth provider like below.

For OAuth users, please replace app.immich:/ with app.immich:///oauth-callback for the Redirect URI in your OAuth provider settings

For more information see the upstream GitHub issue.

  • 2 min read

Build apt-packages for the dependencies

The build time has been abysmal, over 40 minutes. Everything from Postgres to Python was built in a single 658 lines snapcraft.yaml file. It has just sort of evolved over time.

This has been one of the classic: I do not have time to fix this, so I have lost time waiting for builds. I have tried to fix this twice, first with cache, and later on with snaps as a dependency. The first one introduced complexity, and the second one did not work that well, I had to fight the tooling.

I known that package the dependencies in deb packages was probably the smart thing to do, but I did not have the energy to figure out how to set it up, so I have stalled. But it's now done, I have created 14 different packages of cgif, ffmpeg, haproxy, imagemagick, lego ,libde265, libheif, libraw, libvips, mimalloc, postgres, python, redis and x265. You can read more about the repository here.

10k feet overview

For the curious, I build the packages in clean OCI images (with Podman). The deb packages are created with fpm and I use Aptly to manage the repository. I have also created a few bash scripts to "build", "add to repo" and "publish" to make life easier for future me.

The observant have seen that I'm down from 40 minutes to 17. I'm actually expected it to be lower but Immich takes a long time to build, and the resulting snap takes several minutes to compress. It's still over twice as fast. I also added a build cache, so if I only tweak the tests, it can reuse the cached snap package. That makes tweaking and troubleshooting much faster.

Why did I do this now?

I had a test failure that only occurred on GitHub, it required a lot of rebuilds. I needed a distraction, and a distraction that also reduce the build time sounded like a good idea. This was also a good time to delay a release a little, this was the purchase a license release and I preferred to wait a little before it resolved it self. There have also not been any breaking changes.

  • 1 min read

We have a new logo. Immich changed logo earlier this year and I have always felt that my old logo was rushed and more of a placeholder. The old logo was the outer ring of Immich old logo with a box in the middle reflecting on the fact that Immich Distribution is a package of Immich.

New Old

I moved "Immich" inside the box in the new logo, it's better reflects what's going on. I also choose to not reuse parts of the new logo due the fact that the new logo is probably trademarked by FUTO. The colored leaves have the same basic shape as the leaves in the new Immich logo. I kept the red theme from the old logo. I feel that this also better reflects that Immich Distribution also contains more things, like databases, extra features and so on.