Upgrade Path

Immich 1.118.0 → 3.2.4

96 versions, 11 with breaking changes, 13 with upstream notes or warnings only (1 repeats an earlier entry), 1 required stop

Required stops

Version by version, oldest first

1.118.1 2024-10-15

Warning

Version v1.118.0 contains breaking changes. Read about them here.

Full release notes for 1.118.1

1.118.2 2024-10-16

Warning

Same text as in 1.118.1, above.

Full release notes for 1.118.2

1.119.0 2024-10-28

Caution

The env variable for the host binding was erroneously named HOST instead of IMMICH_HOST (which is how it was listed in the docs). This has been corrected in this release. If you were using the HOST env var in your setup before, please update it to IMMICH_HOST.

If you are using the built-in Prometheus endpoint for monitoring, please read on. If not, you can ignore this section.

The following env variables have been removed:

  • IMMICH_METRICS
  • IMMICH_API_METRICS
  • IMMICH_HOST_METRICS
  • IMMICH_IO_METRICS
  • IMMICH_JOB_METRICS

Use IMMICH_TELEMETRY_INCLUDE / IMMICH_TELEMETRY_EXCLUDE instead.

Examples:

-- IMMICH_METRICS=true
++ IMMICH_TELEMETRY_INCLUDE=all
-- IMMICH_METRICS=true
-- IMMICH_HOST_METRICS=false
++ IMMICH_TELEMETRY_INCLUDE=all
++ IMMICH_TELEMETRY_EXCLUDE=host
-- IMMICH_API_METRICS=true
-- IMMICH_HOST_METRICS=true
++ IMMICH_TELEMETRY_INCLUDE=api,host

Breaking

Full release notes for 1.119.0

1.119.1: no action items (1 version)

1.120.0 2024-11-06

Note

Note for third-party Immich distributions: as this filter only exists in jellyfin-ffmpeg, please ensure you use this build instead of a standard FFmpeg build.

Full release notes for 1.120.0

1.120.1 – 1.121.0: no action items (3 versions)

1.122.0 2024-12-05

Note

Some videos may appear warped when viewing. If this occurs, please sign out and sign back in. This only needs to be done once and does not apply to new app installations on 1.122.0 or later.

Note

This feature requires always granting precise location permission for the Immich app so it can read the Wi-Fi name in both foreground and background.

Breaking

Full release notes for 1.122.0

1.122.1 – 1.124.2: no action items (7 versions)

1.125.1 2025-01-23

Important

If you are running remote machine learning, please make sure the remote service pulls the latest version.

Important

For uploading photos from the gallery, it is still recommeded to use the built-in backup feature since the share-to mechanism that can cause mismatching upload status. Additionally, iOS defaults to sharing an exported JPEG image instead of the original for formats like HEIC. You can change this by tapping “Options” near the top of the iOS sharing menu and selecting “Current” instead of “Automatic”.

Breaking

Full release notes for 1.125.1

1.125.2 – 1.126.1: no action items (7 versions)

1.127.0 2025-02-26

Breaking

Full release notes for 1.127.0

1.128.0 – 1.129.0: no action items (2 versions)

1.130.0 2025-03-25

Note

Possible breaking change: If you use creative exclusion patterns for your libraries, please check if these are still respected and report any issues to us.

Full release notes for 1.130.0

1.130.1 – 1.131.3: no action items (7 versions)

1.132.0 2025-04-23

Note

We are now using Valkey's image for the Redis service in the default docker-compose.yml template. This is not a required change. If you wish to use it, you can download the docker-compose.yml file at the bottom of the release notes and replace the redis image with the new one.

Breaking

Full release notes for 1.132.0

1.132.1: no action items (1 version)

1.132.3 2025-04-28

Required stop

See required stops, above

Important

Please update your Authelia config with the following property

token_endpoint_auth_method: "client_secret_post"

Full release notes for 1.132.3

1.133.0 2025-05-21

Breaking

  1. Mobile app version

Please make sure to have the mobile app and the server on the same version for this release. Older versions of the mobile app will not work correctly with version v1.133.0 of the server. At the time of this release, the updated version of the mobile app should be available on the app stores.

  1. Upgrading the server from a very old release

As of 1.133.0, Immich only supports upgrading directly from 1.107.2 or later. If you’re trying to upgrade a version of Immich below this, please upgrade to 1.107.2 first and ensure Immich starts up successfully before continuing to the latest release.

  1. New database vector extension

We are migrating off the deprecated pgvecto.rs database extension to its successor VectorChord, which comes with performance improvements in almost all aspects. This change is a major milestone we want to perform prior to the stable release.

Before making any other changes, please back up your database. While every effort has been made to make this migration as smooth as possible, there’s always a chance that something can go wrong.

After making a backup, please modify your docker-compose.yml file with the following information.

  [...] 

  database:
    container_name: immich_postgres
-   image: docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0@sha256:739cdd626151ff1f796dc95a6591b55a714f341c737e27f045019ceabf8e8c52
+   image: ghcr.io/immich-app/postgres:14-vectorchord0.3.0-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
+     # Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
+     # DB_STORAGE_TYPE: 'HDD'
    volumes:
      # Do not edit the next line. If you want to change the database storage location on your system, edit the value of DB_DATA_LOCATION in the .env file
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
-   healthcheck:
-     test: >-
-       pg_isready --dbname="$${POSTGRES_DB}" --username="$${POSTGRES_USER}" || exit 1;
-       Chksum="$$(psql --dbname="$${POSTGRES_DB}" --username="$${POSTGRES_USER}" --tuples-only --no-align
-       --command='SELECT COALESCE(SUM(checksum_failures), 0) FROM pg_stat_database')";
-       echo "checksum failure count is $$Chksum";
-       [ "$$Chksum" = '0' ] || exit 1
-     interval: 5m
-     start_interval: 30s
-     start_period: 5m
-   command: >-
-     postgres
-     -c shared_preload_libraries=vectors.so
-     -c 'search_path="$$user", public, vectors'
-     -c logging_collector=on
-     -c max_wal_size=2GB
-     -c shared_buffers=512MB
-     -c wal_compression=on
    restart: always

    [...]

Important

Note: after switching to VectorChord, you should not downgrade Immich below 1.133.0.

Note

Your Immich instance must be accessed through a public HTTPS endpoint in order for the casting device to successfully load media. Accessing the instance and casting from a private HTTPS endpoint (or an HTTP endpoint) will result in the cast receiver failing to load any media.

Breaking

Full release notes for 1.133.0

1.133.1 – 1.135.3: no action items (6 versions)

1.136.0 2025-07-24

Breaking

IMMICH_MEDIA_LOCATION (#19995)

Note: This is a different variable than UPLOAD_LOCATION, which requires no change.

Note: if you DO NOT have IMMICH_MEDIA_LOCATION in your .env file, or if it is set to a path that starts with a / (absolute path), THIS BREAKING CHANGE DOES NOT APPLY TO YOU. Users of the all-in-one image (e.g., the unraid app) for instance are not affected.

If you have a custom IMMICH_MEDIA_LOCATION environment variable set to a relative path, you will have to do the following process:

  1. Stop Immich (docker compose stop):
  2. Update Immich (docker compose pull)
  3. Update the environment variable to an absolute path, for example:
-IMMICH_MEDIA_LOCATION=./my-library
+IMMICH_MEDIA_LOCATION=/usr/src/app/my-library
  1. Start Immich (docker compose up -d --force-recreate)
  2. After the server successfully starts up, connect to it (docker exec ``*-it*`` immich_server /bin/sh) and run immich-admin change-media-location. When prompted, enter the appropriate values. For example:
docker exec -it immich_server /bin/sh

$ immich-admin change-media-location
...
? Enter the previous value of IMMICH_MEDIA_LOCATION: ./my-library
? Enter the new value of IMMICH_MEDIA_LOCATION: /usr/src/app/my-library

  Previous value: ./my-library
  Current value:  /usr/src/app/my-library

  Changing database paths from "my-library/*" to "/usr/src/app/my-library/*"

? Do you want to proceed? [Y/n] y

Matching database file paths were updated successfully! 🎉

You may now set IMMICH_MEDIA_LOCATION=/usr/src/app/my-library and restart!

Background/Motivation

Relative paths have implied ambiguity, as they depend on the current working directory to resolve correctly, leading to issues like (#4465). This change removes this ambiguity and sets up the project to transition away from files living at /usr/src/app/upload entirely. Currently, the upload folder lives at /usr/src/app/upload/upload, which is very confusing… for everyone. This change opens to door for a future migration to something like IMMICH_DATA=/data, which a more sensible setup.

API Key changes (#20113)

Note: This change may affect the use of third-party applications, such as ImmichGo, ImmichKios, or ImmichFrame.

This release includes a change to how API Keys work, specifically when used with routes that don’t require a specific permission. Previously, a scoped API Key could access these routes, but they will now throw a forbidden error. Routes without a declared scope now implicitly require the “all” permission.

Note

This is only supported when both the server and the mobile app are updated to v1.136.0

Breaking

Full release notes for 1.136.0

1.137.0 2025-07-31

Breaking

If your current, running version of Immich is v1.132.0 or newer, there is NO ACTION required. If you are updating from version below v1.132.0 continue reading.

Remove TypeORM (#20366)

This update requires applications to have started up at least once on 1.132.0+. See https://immich.app/errors#typeorm-upgrade for more details.

Caution

Related to these changes, a few API permissions have been renamed. See #20250 for more details.

Breaking

Full release notes for 1.137.0

1.137.1 – 1.137.3: no action items (2 versions)

1.138.0 2025-08-14

Important

For users that are using the beta timeline, please update your server to v1.138.0 so that the sync mechanism can work correctly. v1.138.0 of the mobile app doesn’t sync the data correctly if your server is v1.137.2 or below.

Breaking

Full release notes for 1.138.0

1.138.1 – 1.142.1: no action items (9 versions)

1.143.0 2025-09-22

Note

If you're still experiencing issues with remote assets or albums not showing up on the mobile app, please ensure that your server is updated to the latest version. If you are still having issues, try logging out and back in.

Full release notes for 1.143.0

1.143.1 – 2.2.3: no action items (9 versions)

2.3.0 2025-11-19

Important

We will start the work on removing the old mobile timeline soon. If you are still using the old timeline, please make sure to switch to the new timeline. If this message does not make sense to you, you can ignore it as you are already on the new timeline

Full release notes for 2.3.0

2.3.1 2025-11-20

Important

We encourage all users to update to this version to avoid the issue that will happen when the next minor update is available, i.e., v2.4.0

Full release notes for 2.3.1

2.4.0 – 2.4.1: no action items (2 versions)

2.5.0 2026-01-27

Note

Reclaim storage To use the reclaimed space right away, you must manually empty the system/gallery trash outside Immich.

Note

Limitations:

  • Mobile clients must be updated to v2.5.0 in order view the edited version of an asset. Clients will continue to > see the original asset if on a mobile app version <2.5.0
  • As of this version, the edited download won't include the EXIF metadata of the original asset. This feature will come in future releases.
  • Mobile editing still uses the old edit system (saving a new version of the photo). The mobile editor will be upgraded to use the new non-destructive editing system in a future release.

Full release notes for 2.5.0

2.5.2 2026-01-29

Note

This version of the mobile app will pull down some data from the server to fix the incorrect data in the mobile app local database, so you will see the sync icon running for a little bit

Full release notes for 2.5.2

2.5.3 – 2.5.6: no action items (3 versions)

2.6.0 2026-03-19

Warning

For those who are still using the old timeline, please switch to the new timeline to avoid interruption, as the old timeline will be removed in the next release.

ps: The old timeline has an exclamation icon next to the logo.

Full release notes for 2.6.0

2.6.1 – 2.6.3: no action items (3 versions)

2.7.0 2026-04-07

Note

Known limitations

  • The machine learning service on amd64 currently requires the >= x86-64-v2 microarchitecture. This will be patched in an upcoming patch release for backward compatibility with very old processors (before ~2010), but it will become a minimum requirement in 3.0. arm64 is not affected by this change.

Full release notes for 2.7.0

2.7.2 – 2.7.5: no action items (4 versions)

3.0.0 2026-07-02

Breaking

This release includes several breaking changes; read the full migration guide here. It's worth mentioning that many of the breaking changes are updates to API endpoints and affect only third-party tools that integrate with Immich's API. For the vast majority of users, updating works exactly as it always has.

Note

How to update

Warning

v3.0.0 drops support for pgvecto.rs. If you run Immich before v1.133.0 and haven't done the migration step yet, see the migration guide here. https://docs.immich.app/install/upgrading/#migrating-to-vectorchord

First, update the IMMICH_VERSION in your .env file to v3:

- IMMICH_VERSION=v2
+ IMMICH_VERSION=v3

Then run the usual update commands:

docker compose pull && docker compose up -d

Note

For assets imported prior to v3, you will also need to re-run Metadata Extraction in the job panel for them to be re-processed.

Breaking

Full release notes for 3.0.0

3.0.1 – 3.0.2: no action items (2 versions)

3.0.3 2026-07-15

Note

In some specific circumstances, newly uploaded Live Photos could have broken thumbnails. If you see any such cases, please run the "missing" job for thumbnails or wait for the respective nightly job to clear it up.

Full release notes for 3.0.3

3.1.0 2026-07-29

Breaking

Full release notes for 3.1.0

3.2.0 – 3.2.4: no action items (4 versions)

Release notes from github.com/immich-app/immich/releases, checked 18 hours ago. Only text the vendor marks as breaking, or puts in a warning/caution/important note, or a plain note, is shown (a note that asks nothing of the admin, such as a call for feedback or testing, is not); read the full notes for anything else.