Immich 3.0: From Home-Lab Darling to Production-Ready Platform

Immich has spent the last few years as the darling of the self-hosted community. Launched in 2022 to counter Google's restrictive cloud storage policies, it quickly became the default open-source alternative to Google Photos. But for a long time, running it felt like riding a unicycle on a tightrope. Updates were frequent, breaking changes were common, and the pace of development was breakneck.

Version 3.0 changes the narrative. This major release signals a transition from a fast-moving hobbyist project to a stable, hardened media platform. By introducing formal release candidates, deterministic web builds, a structured automation engine, and strict database migrations, the development team is building a platform that developers can confidently deploy and extend.

Database Hardening and Platform Maturity

The most significant architectural change in Immich 3.0 is under the hood. The release officially drops support for the pgvecto.rs vector database extension. If you are running an older instance (prior to v1.133.0) and haven't migrated to VectorChord yet, you must perform this database migration step before upgrading to v3.0.0.

Vector search is the backbone of Immich's machine learning capabilities, powering facial recognition and CLIP-based semantic search. Shifting vector backends is a heavy database-level operation. By deprecating the older extension and standardizing on VectorChord, the team is streamlining the database schema and reducing the maintenance overhead of supporting multiple vector backends.

To address the common pain point of database drift, Immich 3.0 introduces built-in integrity checks. In any self-hosted storage system, files on disk can occasionally fall out of sync with the database due to manual file moves, disk corruption, or interrupted backups. The new integrity check scans storage directories, compares files on disk with PostgreSQL records, and flags untracked files, missing files, or checksum mismatches.

Additionally, the web builds are now completely deterministic. For developers concerned with supply chain security and reproducible builds, this ensures that compiling the frontend from source yields the exact same byte-for-byte output as the official releases.

The Developer Angle: API Breaks and JSON Workflows

For standard users, the upgrade path to v3.0.0 is straightforward. It requires updating the environment variable in your configuration and pulling the new images:

# In your .env file
- IMMICH_VERSION=v2
+ IMMICH_VERSION=v3

Then, run the standard Docker Compose commands to pull and restart the containers:

docker compose pull && docker compose up -d

However, developers building on top of Immich need to pay close attention. Version 3.0 introduces several breaking changes to the API endpoints. If you maintain a third-party CLI, a desktop uploader, or an alternative client, you will need to audit your API integrations against the migration guide.

On the extensibility front, the headline feature is the preview of Workflows. Located under Utilities on the web interface, Workflows allow you to automate actions in your media library by chaining triggers, filters, and actions.

flowchart TD
    Trigger[Trigger: e.g., Asset Uploaded] --> Filter{Filter: Check Conditions}
    Filter -- Match --> Action[Action: e.g., Tag or Move Asset]
    Filter -- No Match --> End[End Process]

Instead of forcing developers to write custom cron jobs or external scripts that poll the Immich API, the platform now has an internal automation engine. The workflow editor supports both a visual drag-and-drop interface and a raw JSON editor. This JSON representation makes it easy to treat your automation workflows as configuration files, allowing you to version-control, share, and import them directly.

Re-Engineering the Mobile and Media Pipelines

Immich 3.0 also brings major improvements to how the platform handles background execution and media processing.

Background Backup Reliability

On Android, the app now uses a new periodic task scheduler. Previously, background backups were often limited to newly captured photos. The new scheduler allows the app to upload your entire library in the background while respecting Android's strict background execution limits. It also detects and warns you if battery optimization or notification settings are blocking the backup process. On iOS, the background refresh task now runs sync and upload tasks in parallel, maximizing the amount of data transferred during the short background execution windows granted by the operating system.

Non-Destructive Editing

Following the web-based image editing introduced in v2.5.0, mobile editing is now non-destructive. The previous mobile editor created entirely new assets on the server when you cropped or rotated an image. The new implementation syncs edit states between mobile and web. You can crop a photo on your phone, open the web app, and revert or adjust that same crop without ever touching the original source file. Note that some older mobile editing features, such as recoloring, live photo editing, and local asset editing, have been temporarily removed to make way for this unified architecture, though the team plans to restore them later.

Real-Time Video Transcoding

Immich 3.0 introduces an experimental preview of HTTP Live Streaming (HLS) and real-time video transcoding for the web app. This allows the server to transcode video files on the fly to match the client's bandwidth and format requirements, paired with a custom web video player that provides consistent controls across devices. Real-time transcoding is resource-intensive; while hardware acceleration is recommended rather than mandatory, running this feature smoothly will require a server with decent CPU or GPU capabilities.

The Verdict

Immich 3.0 is a clear sign of a project growing up. By moving to a structured release candidate model, the maintainers are prioritizing stability over raw speed. The introduction of the JSON-based workflow engine and the cleanup of the database layer make the platform far more attractive for developers who want to build custom integrations or run large-scale self-hosted media libraries.

If you are running third-party tools that rely on the Immich API, take a moment to test them against the new release candidates before updating your production instance. Otherwise, the performance improvements to the timeline rendering and the reliability upgrades to the mobile backup engine make this a highly recommended upgrade.