Immich 1.107.0 → 3.2.4

This release includes a security update for Node.js. While we don't think these CVEs affect Immich, we strongly recommend you update. For more details, see https://nodejs.org/en/blog/vulnerability/july-2024-security-releases.

Read our announcement about supporting Immich by buying a license here

If you use CUDA for machine learning, the minimum NVIDIA driver version is now 545 from 535.

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

• feat(server): granular permissions for api keys by @jrasm91 in https://github.com/immich-app/immich/pull/11824
• refactor(server): stacks by @jrasm91 in https://github.com/immich-app/immich/pull/11453
• fix(server): album statistics endpoint by @jrasm91 in https://github.com/immich-app/immich/pull/11924
• fix: remove asset.resized by @jrasm91 in https://github.com/immich-app/immich/pull/11983
• fix(mobile): use a valid OAuth callback URL by @qrkourier in https://github.com/immich-app/immich/pull/10832

NOTE: these changes apply to the metadata extraction job. To apply them to your photos and videos, re-run metadata extraction.

The image section of the config file structure for thumbnails and previews has changed. If you use a config file and set the image settings to custom values, these will be ignored until updated to the new structure.

…
"image": {
-  “previewFormat”: “jpeg”,
-  “previewSize”: 1440,
-  “quality”: 80,
-  “thumbnailFormat”: “webp”,
-  “thumbnailSize”: 250,
+  "thumbnail": {
+     "format": "webp",
+     "size": 250,
+     "quality": 80
+   },
+   "preview": {
+     "format": "jpeg",
+     "size": 1440,
+     "quality": 80
+   },
    "colorspace": "p3",
    "extractEmbedded": false
  }
…

This release includes the following breaking changes:

1. Port alignment
2. Remove deprecated API endpoints
3. Remove deprecated start.sh arguments

1. Port alignment

We aligned the internal port of the immich-server to be similar to the binding port. Please make the following change to your docker-compose.yml file under the immich-server section. Reverse proxies using port 3001 also need to be updated to use port 2283.

services:
  immich-server:
    container_name: immich_server
    ...
    ports:
-    - 2283:3001
+    - 2283:2283
    ...

2. Remove deprecated API endpoints

The following endpoints were previously deprecated and have been removed, if you are a community project maintainer and using one of the endpoints below, please make sure to make changes to your project:

• /api/server-info/* has been removed. Use /api/server/* instead.
• /api/people/:id/assets has been removed. Use /api/search/metadata instead.

Note

This includes /api/server-info/ping, /api/server-info/version, /api/server-features, /api/server-info/config, /api/server-info/statistics, and others.

3. Remove deprecated start.sh arguments

The following docker commands have been removed:

• start.sh immich
• start.sh microservices

Follow the steps below to align docker-compose.yml with the default setup.

Note

These steps are only required if you still have the immich-microservices section in your docker-compose.yml or didn't follow the previous instructions to remove the command section. If you don't have the mentioned content below, you can ignore this

1. Update docker-compose.yml

Remove the command line from immich-server and the entire immich-microservices service section as shown below.

services:
  immich-server:
    container_name: immich_server
    ...
    :
-   command: [ "start.sh", "immich" ]
    ...
    
-  immich-microservices:
-    container_name: immich_microservices
-    ...
-    :
-    command: [ "start.sh", "microservices" ]
-    ...

2. Remove the running immich-microservices container

Run docker compose down --remove-orphans after updating docker-compose.yml to remove the old immich-microservices container.

• refactor(server): worker env by @jrasm91 in https://github.com/immich-app/immich/pull/13160
• chore: remove deprecated controller by @jrasm91 in https://github.com/immich-app/immich/pull/13189
• chore: remove deprecated endpoint by @jrasm91 in https://github.com/immich-app/immich/pull/13190
• feat: align compose ports by @jrasm91 in https://github.com/immich-app/immich/pull/13185

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

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

• refactor(server): move host env to config repo by @jrasm91 in https://github.com/immich-app/immich/pull/13507
• refactor(server): telemetry env variables by @danieldietzler in https://github.com/immich-app/immich/pull/13705

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.

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.

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.

• refactor: rename searchMetadata to searchAssets by @jrasm91 in https://github.com/immich-app/immich/pull/14151

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

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”.

• chore(server)!: default max bitrate unit to kbps by @mertalev in https://github.com/immich-app/immich/pull/15264
• feat: better spec urls by @jrasm91 in https://github.com/immich-app/immich/pull/15487

• chore: removed unused endpoint by @jrasm91 in https://github.com/immich-app/immich/pull/16167

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.

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.

• refactor: notification-admin controller by @jrasm91 in https://github.com/immich-app/immich/pull/17748

Please update your Authelia config with the following property

token_endpoint_auth_method: "client_secret_post"

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.

2. 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.

3. 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

    [...]

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

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.

• refactor: user avatar color by @jrasm91 in https://github.com/immich-app/immich/pull/17753
• chore: remove old memory lane implementation by @jrasm91 in https://github.com/immich-app/immich/pull/18000
• feat: vectorchord by @mertalev in https://github.com/immich-app/immich/pull/18042

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

4. Start Immich (docker compose up -d --force-recreate)
5. 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.

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

• feat!: absolute file paths by @jrasm91 in https://github.com/immich-app/immich/pull/19995
• fix: default route permission by @jrasm91 in https://github.com/immich-app/immich/pull/20113

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.

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

• feat!: more permissions by @jrasm91 in https://github.com/immich-app/immich/pull/20250
• feat!: remove typeorm by @jrasm91 in https://github.com/immich-app/immich/pull/20366

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.

• fix: album asset sync must sync new assets in a shared album by @zackpollard in https://github.com/immich-app/immich/pull/20655

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.

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

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

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

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.

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

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.

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.

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.

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

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.

• refactor!: migrate class-validator to zod by @timonrieger in https://github.com/immich-app/immich/pull/26597
• refactor!: remove replace asset by @jrasm91 in https://github.com/immich-app/immich/pull/27022
• refactor!: remove my shared link dto by @jrasm91 in https://github.com/immich-app/immich/pull/27023
• chore!: remove deprecated env variables by @jrasm91 in https://github.com/immich-app/immich/pull/27802
• chore!: remove getRandom api endpoint by @bwees in https://github.com/immich-app/immich/pull/27780
• chore!: remove unused token response param by @jrasm91 in https://github.com/immich-app/immich/pull/27805
• refactor: yeet old timeline by @shenlong-tanwen in https://github.com/immich-app/immich/pull/27666
• chore!: remove old timeline sync endpoints by @jrasm91 in https://github.com/immich-app/immich/pull/27804
• chore!: remove deviceId and deviceAssetId by @danieldietzler in https://github.com/immich-app/immich/pull/27818
• chore!: rename API key schemas by @jrasm91 in https://github.com/immich-app/immich/pull/27828
• chore!: remove without assets by @jrasm91 in https://github.com/immich-app/immich/pull/27835
• fix: oauth issuerUrl validation by @bo0tzz in https://github.com/immich-app/immich/pull/27848
• fix!: do not allow insecure oauth requests by default by @bo0tzz in https://github.com/immich-app/immich/pull/27844
• fix!: set duration to null when not present by @meesfrensel in https://github.com/immich-app/immich/pull/26982
• chore!: remove /api/server/theme endpoint by @jrasm91 in https://github.com/immich-app/immich/pull/27880
• chore!: migrate album owner to album_user by @danieldietzler in https://github.com/immich-app/immich/pull/27467
• refactor!: change number to integer types by @timonrieger in https://github.com/immich-app/immich/pull/27912
• refactor(server)!: move correlationId to X-Correlation-ID response header by @timonrieger in https://github.com/immich-app/immich/pull/28139
• refactor(server)!: remove redundant error and statusCode fields from error responses by @timonrieger in https://github.com/immich-app/immich/pull/28140
• chore(server)!: drop pgvecto.rs support by @mertalev in https://github.com/immich-app/immich/pull/28159
• chore!: duration in milliseconds by @mertalev in https://github.com/immich-app/immich/pull/28003
• refactor(server)!: sanitize error messages to avoid leaking resource details by @timonrieger in https://github.com/immich-app/immich/pull/28154
• refactor(server)!: structured validation error responses by @timonrieger in https://github.com/immich-app/immich/pull/28204
• feat(server)!: add isOwned filter to albums API by @timonrieger in https://github.com/immich-app/immich/pull/28213
• chore(ml)!: require numpy 2.4 by @mertalev in https://github.com/immich-app/immich/pull/28158
• fix(deps): update dependency nestjs-otel to v8 by @renovate[bot] in https://github.com/immich-app/immich/pull/27863
• chore(ml)!: remove deprecated envs by @mertalev in https://github.com/immich-app/immich/pull/28326
• chore(server)!: remove libopus enum by @mertalev in https://github.com/immich-app/immich/pull/28325
• refactor!: remove asset faces from AssetResponseDto by @bwees in https://github.com/immich-app/immich/pull/27779
• refactor(server)!: drop empty string to null conversion by @timonrieger in https://github.com/immich-app/immich/pull/28808
• refactor(server)!: remove changeExpiryTime by @timonrieger in https://github.com/immich-app/immich/pull/28816
• refactor!: disallow star rating < 1 by @meesfrensel in https://github.com/immich-app/immich/pull/27896
• fix!: search endpoints visibility can be omitted by @danieldietzler in https://github.com/immich-app/immich/pull/29385

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.

• chore(mobile): drop support for iOS 14 by @agg23 in https://github.com/immich-app/immich/pull/29780