docs(openapi): Add descriptions to OpenAPI specification by timonrieger · Pull Request #25185 · immich-app/immich

timonrieger · 2026-01-10T13:48:23Z

Description

This PR enhances the OpenAPI specification documentation by adding descriptions to ~~API endpoints, request/response models, and~~ schema properties. The primary goal is to improve API usability and developer experience by providing clear documentation throughout the OpenAPI spec, clients and documentation pages.

The focus of this PR is exclusively on adding descriptions and documentation comments. No functional changes, API modifications, or breaking changes are included. All changes are purely additive documentation improvements. (see Verification Script below)

How Has This Been Tested?

Verified that generated code outputs match main branch (cross-checked when generating code)
Confirmed that only description additions and comments are present in the diff
Verified that no functional changes were introduced

The following script can be used to verify that the diff only contains comments and description additions:

#!/bin/bash
# Check if diff only contains comments and description additions

echo "=== Checking mobile/openapi ==="
NON_COMMENT_CHANGES=$(git diff main -- mobile/openapi/ | grep -E "^\+[^+]" | grep -v "^\+[[:space:]]*//" | grep -v "^\+[[:space:]]*/\*" | grep -v "^\+[[:space:]]*\*" | grep -v "^+++" | wc -l)
if [ "$NON_COMMENT_CHANGES" -eq 0 ]; then
  echo "✓ Only comment changes in mobile/openapi"
else
  echo "✗ Found $NON_COMMENT_CHANGES non-comment additions in mobile/openapi"
fi

echo ""
echo "=== Checking open-api/typescript-sdk ==="
NON_COMMENT_CHANGES_TS=$(git diff main -- open-api/typescript-sdk/ | grep -E "^\+[^+]" | grep -v "^\+[[:space:]]*//" | grep -v "^\+[[:space:]]*/\*" | grep -v "^\+[[:space:]]*\*" | grep -v "^+++" | wc -l)
if [ "$NON_COMMENT_CHANGES_TS" -eq 0 ]; then
  echo "✓ Only comment changes in open-api/typescript-sdk"
else
  echo "✗ Found $NON_COMMENT_CHANGES_TS non-comment additions in open-api/typescript-sdk"
  echo "Showing non-comment changes:"
  git diff main -- open-api/typescript-sdk/ | grep -E "^\+[^+]" | grep -v "^\+[[:space:]]*//" | grep -v "^\+[[:space:]]*/\*" | grep -v "^\+[[:space:]]*\*" | grep -v "^+++"
fi

echo ""
echo "=== Checking JSON spec for non-description changes ==="
NON_DESC_CHANGES=$(git diff main -- open-api/immich-openapi-specs.json | grep "^\+" | grep -v "description" | grep -v "^+++" | grep -vE "^\+[[:space:]]*[]}],?[[:space:]]*$" | wc -l)
if [ "$NON_DESC_CHANGES" -eq 0 ]; then
  echo "✓ Only description additions in JSON spec"
else
  echo "✗ Found $NON_DESC_CHANGES non-description additions in JSON spec"
  echo "Showing non-description changes:"
  git diff main -- open-api/immich-openapi-specs.json | grep "^\+" | grep -v "description" | grep -v "^+++" | grep -vE "^\+[[:space:]]*[]}],?[[:space:]]*$"
fi

Running it, gives the output below. The three changes found in the JSON spec are trailing comma additions due to added descriptions:

bash check.sh
=== Checking mobile/openapi ===
✓ Only comment changes in mobile/openapi

=== Checking open-api/typescript-sdk ===
✓ Only comment changes in open-api/typescript-sdk

=== Checking JSON spec for non-description changes ===
✗ Found        3 non-description additions in JSON spec
Showing non-description changes:
+            "default": "editor",
+            "default": "desc",
+            "default": "desc",

I also manually reviewed all of the changes myself!

Previewing Descriptions

Copy this HTML code to a local file and open it in your browser. This generates the Scalar OpenAPI documentation for this PR including all the descriptions. To compare this PR's with main's output, uncomment the url above.

<!doctype html>
<html>
  <head>
    <title>Scalar API Reference</title>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <div id="app"></div>
    <!-- Load the Script -->
    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
    <!-- Initialize the Scalar API Reference -->
    <script>
      Scalar.createApiReference('#app', {
        // The URL of the OpenAPI/Swagger document
        // url: 'https://raw.githubusercontent.com/immich-app/immich/main/open-api/immich-openapi-specs.json',
        url: 'https://raw.githubusercontent.com/timonrieger/immich/docs/add-openapi-descriptions/open-api/immich-openapi-specs.json',
        // Avoid CORS issues
        proxyUrl: 'https://proxy.scalar.com',
      })
    </script>
  </body>
</html>

Checklist:

I have performed a self-review of my own code
I have made corresponding changes to the documentation if applicable
I have no unrelated changes in the PR.
I have confirmed that any new dependencies are strictly necessary.
I have written tests for new code (if applicable)
I have followed naming conventions/patterns in the surrounding code
All code in src/services/ uses repositories implementations for database calls, filesystem operations, etc.
All code in src/repositories/ is pretty basic/simple and does not have any immich specific logic (that belongs in src/services/)

Please describe to which degree, if any, an LLM was used in creating this pull request.

This PR was created with assistance from an LLM to generate comprehensive descriptions. I made 100% sure that no other than descriptions were added afterwards.

timonrieger · 2026-01-10T15:39:46Z

Even if you not agree with a lot of descriptions, we could do a followup PR for that or along the way in the future. the goal is to have the structure and heavy lift in place and only having to tweak the description itself in the future.

timonrieger · 2026-01-10T16:12:38Z

all request bodies and query/path params have a description now. ~~Still tbd are response and schema descriptions (if wanted)~~ these are also done now

timonrieger · 2026-01-11T13:50:28Z

@jrasm91 not sure if I understood fully what you mean, but after applying your suggestions, we lose information in the generated spec, see 6a19910

from what I see from my test in that commit and some ressearch:

OpenAPI has operation-level fields that DTOs can’t populate. requestBody.description and parameter descriptions come from @ApiBody / @ApiParam; moving docs to DTO JSDoc drops that data, as seen in the patch.
JSDoc is descriptive text, not schema control. It can’t reliably express OpenAPI constraints (e.g. integer vs number, formats, nullability), which is why types regressed when explicit Swagger metadata was removed.
Type inference also can’t infer human-facing descriptions. Those strings were explicit decorator metadata.
So relying only on JSDoc + inference reduces duplication, but also reduces OpenAPI fidelity. For deterministic output—operation docs, request/param descriptions, and precise schema typing—explicit Swagger metadata is still required.

timonrieger · 2026-01-13T18:35:06Z

@jrasm91 how do we continue here?

jrasm91 · 2026-01-13T18:56:47Z

I don't think this will get merged as is. I'm strongly against duplicating type information that's already inferred correctly today, just for the sake of adding comments.

timonrieger · 2026-01-24T17:11:57Z

@jrasm91 i applied the proposal from #25479, by cleaning up all other changes and exclusively keeping the ApiProperty ones.

I decided against implementing our Property object instead of nestjs' ApiProperty due to mixing of concerns. Prior to this PR there have been some ApiProperty annotations being used, so I did not want to change those now. I'd rather do this change for all properties in a separate PR.

One more note: there are properties that have a type which itself is a schema. For those i added the ApiProperty with description: undefined.

+  // Description lives on schema to avoid duplication
+  @ApiProperty({ description: undefined })
   albumUsers!: AlbumUserResponseDto[];

Why undefined? The schema should define the description via ApiSchema, otherwise we will end up with duplicate descriptions of the schema, depending on the context being used.
The schema description would be implemented like this
```
+ @ApiSchema({ description: "description for the schema would go here and act as the single source of truth" }))
  export class AlbumUserResponseDto {
```
However, if (in the future) the context requires some more explicit descriptions for a (schema) property, we could override the `undefined` value. I added a comment above all these cases.
Why define it at all if it's not necessary? Technically it would be possible to remove those if kept it for explicity and future reference.

Once merged I will followup this PR with:

Changing all ApiProperty implementations to Property + HistoryBuilder
Add schema descriptions with ApiSchema
Add query param descriptions with ApiQuery docs(openapi): add descriptions for query params #25491

timonrieger · 2026-01-24T17:46:24Z

one more thing we could optimize is to remove the ApiProperty from enum properties since they already get their description via the ValidateEnum decorator. This behaviour was introduced in #19943

Like this

This would have no impact on the generated openapi output since `ValidateEnum` accepts a description

-  @ApiProperty({ description: 'Activity type (like or comment)', enum: ReactionType })
  @ValidateEnum({ 
    enum: ReactionType, 
    name: 'ReactionType',
+   description: 'Activity type (like or comment)',
  })
  type!: ReactionType;

Alternatively we remove the ApiProperty decorator from this decorator and apply it separately, so its explicit instead of implicit.

Like this

validation.ts

type EnumOptions<T> = {
  enum: T;
-  name: string;
  each?: boolean;
  optional?: boolean;
  nullable?: boolean;
-  default?: T[keyof T];
-  description?: string;
};
export const ValidateEnum = <T extends object>({
- name,
  enum: value,
  each,
  optional,
  nullable,
- default: defaultValue,
- description,
}: EnumOptions<T>) => {
  return applyDecorators(
    optional ? Optional({ nullable }) : IsNotEmpty(),
    IsEnum(value, { each }),
-    ApiProperty({ enumName: name, enum: value, isArray: each, default: defaultValue, description }),
  );
};

time-bucket.dto.ts

+  @ApiProperty({ description: 'Filter by asset visibility status (ARCHIVE, TIMELINE, HIDDEN, LOCKED)' })
  @ValidateEnum({
    enum: AssetVisibility,
-    name: 'AssetVisibility',
    optional: true,
-    description: 'Filter by asset visibility status (ARCHIVE, TIMELINE, HIDDEN, LOCKED)',
  })

jrasm91 · 2026-01-26T15:52:14Z

You are changing the specification and introducing bugs because of it. Maybe you should submit smaller requests that gradually add descriptions to sections of the app, that way we can review all the changes and make sure nothing unintentional is being introduced. I'm specifically worried about places that @ApiProperty is added, leading to changes in inferred types, like this one:

timonrieger · 2026-01-26T23:05:57Z

You are changing the specification and introducing bugs because of it. Maybe you should submit smaller requests that gradually add descriptions to sections of the app, that way we can review all the changes and make sure nothing unintentional is being introduced. I'm specifically worried about places that @ApiProperty is added, leading to changes in inferred types, like this one:

hmm, i get the point. Should i go ahead and separate the PR into smaller ones? Or should i go ahead and iron out all the introduced bugs (aka spec changes) here?

jrasm91 · 2026-01-26T23:48:59Z

Separate ones would probably be better from my side with regards to reviewing and merging.

mobile/openapi/lib/model/people_update_item.dart

timonrieger · 2026-01-27T12:03:24Z

Separate ones would probably be better from my side with regards to reviewing and merging.

I am jumping back sry, but could you try the verification script in the PR description? it analyzes the diff to check whether there are non-description changes in the generated code. This helps reviewing that part of the change. Below find the result of running the script against this PR diff.

I also re-reviewed the whole diff myself and reverted all of the spec changes introduced in this PR. check the last 5 commits for details.

Unless you are not a fan of this, I'll go ahead with multiple PRs. Although i think that might not be the most time-respecting approach for both of us 😄

jrasm91 · 2026-01-27T14:11:44Z

server/src/dtos/activity.dto.ts

+  @ApiProperty({ description: 'Activity type', enum: ReactionType })
  @ValidateEnum({ enum: ReactionType, name: 'ReactionType' })


Suggested change

@ApiProperty({ description: 'Activity type', enum: ReactionType })

@ValidateEnum({ enum: ReactionType, name: 'ReactionType' })

@ValidateEnum({ enum: ReactionType, name: 'ReactionType', description: 'Activity type' })

We made @ValidateEnum in part to enforce that all enums are assigned a name and externalized as schema. Without enumName: ReactionType, the enum will be inlined and this is not desirable.

Given, that we will continue to want this behavior, I think we should just pass description for all these cases instead of adding a second decorator.

jrasm91 · 2026-01-27T14:13:44Z

server/src/dtos/album.dto.ts

-   * Ignores the shared parameter
-   * undefined: get all albums
-   */
+  @ApiPropertyOptional({ description: 'Filter albums containing this asset ID (ignores shared parameter)' })


The same thing applies here. @ValidateBoolean already takes into account optional?: boolean to enforce validation at runtime and correctly set the correct specification attributes for the property. There is no value adding a second decorator and needing to keep the optional part in sync. AGain, you can simply pass description to @ValidateBoolean and everything should continue to work the same.

This is still unresolved.

jrasm91 · 2026-01-27T14:16:24Z

server/src/dtos/api-key.dto.ts

+  @ApiPropertyOptional({ description: 'List of permissions', enum: Permission, isArray: true })
  @ValidateEnum({ enum: Permission, name: 'Permission', each: true, optional: true })


{ each: true } and { isArray: true } are duplicated here and we do not want to have to keep multiple properties in sync. Let's remove all the @ApiProperty* decorators from properties that already have @Validate* ones on them. In the future I think the plan will be to migrate all properties to use @Validate* style decorators.

should i add the @Validate* decorators where obvious, or strictly just there where they are existing already. e.g.:

Let's keep it as is and make those changes in a follow up PR

jrasm91 · 2026-01-27T14:22:53Z

server/src/dtos/library.dto.ts

 export class ValidateLibraryResponseDto {
+  @ApiPropertyOptional({
+    description: 'Validation results for import paths',
+    type: () => [ValidateLibraryImportPathResponseDto],


Why are you adding this type, which was working before just fine without it here?

jrasm91 · 2026-01-27T14:23:30Z

server/src/dtos/map.dto.ts


 export class MapReverseGeocodeResponseDto {
-  @ApiProperty()
+  @ApiProperty({ description: 'City name', nullable: true })


nullable: true was correctly inferred before. Why is it explicitly added here now?

jrasm91 · 2026-01-27T14:25:20Z

server/src/dtos/model-config.dto.ts

+  @ApiProperty({
+    type: 'number',
+    format: 'double',
+    description: 'Minimum confidence score for text recognition (0.1-1)',


The min and max are already added and included in the specification file as additional metadata, so I don't think it makes to copy it manually to the description, as that's likely to get out of date now. Instead, if we want to include it in the description, we could use a decorator like ValidateNumber({ min, max, description }) and code the implementation to automatically append something like that to the description.

should I add this decorator in this PR direclty? or keep it focused on descriptions only?

Let's do it in a follow up PR

timonrieger · 2026-01-27T16:55:55Z

@jrasm91 applied all the fixes you suggested. you were right, the type inference was useless, same for the nullable annotation. I merged all descriptions into the validator decorator if one already existed.

i pushed all changes in bab5cff, the spec did not change besides some description changes

jrasm91

What you did so far looks really good. You missed a bunch of decorators that should be merged into the matching @Validate* decorators though. Once those are fixed I think this will be ready to merge.

jrasm91 · 2026-01-27T19:31:39Z

server/src/dtos/activity.dto.ts

+  @ApiProperty({ description: 'Album ID' })
  @ValidateUUID()
  albumId!: string;

+  @ApiPropertyOptional({ description: 'Asset ID (if activity is for an asset)' })
  @ValidateUUID({ optional: true })


description can be merged into @ValidateUUID

jrasm91 · 2026-01-27T19:32:01Z

server/src/dtos/album.dto.ts

 import { Optional, ValidateBoolean, ValidateEnum, ValidateUUID } from 'src/validation';

 export class AlbumInfoDto {
+  @ApiPropertyOptional({ description: 'Exclude assets from response' })


Description can be merged into ValidateBoolean()

jrasm91 · 2026-01-27T19:32:11Z

server/src/dtos/album.dto.ts

+  @ApiProperty({ description: 'User ID' })
  @ValidateUUID()


jrasm91 · 2026-01-27T19:32:37Z

server/src/dtos/album.dto.ts

  @Type(() => AlbumUserCreateDto)
  albumUsers?: AlbumUserCreateDto[];

+  @ApiPropertyOptional({ description: 'Initial asset IDs' })


jrasm91 · 2026-01-27T19:33:09Z

server/src/dtos/album.dto.ts

 }

 export class GetAlbumsDto {
+  @ApiPropertyOptional({


jrasm91 · 2026-01-27T19:49:19Z

server/src/dtos/system-metadata.dto.ts

+  @ApiProperty({ description: 'Is admin onboarded' })
  @ValidateBoolean()
  isOnboarded!: boolean;
 }

 export class AdminOnboardingResponseDto {
+  @ApiProperty({ description: 'Is admin onboarded' })
  @ValidateBoolean()


jrasm91 · 2026-01-27T19:49:25Z

server/src/dtos/tag.dto.ts

  @IsString()
  @IsNotEmpty()
  name!: string;

-  @ValidateUUID({ optional: true, nullable: true })
+  @ApiPropertyOptional({ description: 'Parent tag ID' })


jrasm91 · 2026-01-27T19:50:02Z

server/src/dtos/user.dto.ts

+  @ApiPropertyOptional({ description: 'Include deleted users' })
  @ValidateBoolean({ optional: true })
  withDeleted?: boolean;

+  @ApiPropertyOptional({ description: 'User ID filter' })
  @ValidateUUID({ optional: true })


jrasm91 · 2026-01-27T19:50:13Z

server/src/dtos/user.dto.ts

+  @ApiPropertyOptional({ description: 'Require password change on next login' })
  @ValidateBoolean({ optional: true })
  shouldChangePassword?: boolean;

+  @ApiPropertyOptional({ description: 'Send notification email' })
  @ValidateBoolean({ optional: true })
  notify?: boolean;

+  @ApiPropertyOptional({ description: 'Grant admin privileges' })
  @ValidateBoolean({ optional: true })


jrasm91 · 2026-01-27T19:50:29Z

server/src/dtos/workflow.dto.ts

  @IsObject()
  @Optional()
  filterConfig?: FilterConfig;
 }

 export class WorkflowActionItemDto {
+  @ApiProperty({ description: 'Plugin action ID' })


hahaha thanks, it's so many files 😄

timonrieger · 2026-01-27T23:05:25Z

okay i think we are finally there 😅 , i used this regex pattern now to find all the relevant blocks to merge: ^\s*@ApiProperty.*\n\s*@Validate.*

…5596)

….5.3 (#3705) This PR contains the following updates: | Package | Update | Change | |---|---|---| | [ghcr.io/immich-app/immich-server](https://github.com/immich-app/immich) | patch | `v2.5.2` → `v2.5.3` | --- ### Release Notes <details> <summary>immich-app/immich (ghcr.io/immich-app/immich-server)</summary> ### [`v2.5.3`](https://github.com/immich-app/immich/releases/tag/v2.5.3) [Compare Source](immich-app/immich@v2.5.2...v2.5.3) #### What's Changed ##### 🐛 Bug fixes - chore: remove random code snippet by [@jrasm91](https://github.com/jrasm91) in [#25677](immich-app/immich#25677) - fix: reset and unsaved change states in editor by [@bwees](https://github.com/bwees) in [#25588](immich-app/immich#25588) - fix: no notification if release check is disabled by [@jrasm91](https://github.com/jrasm91) in [#25688](immich-app/immich#25688) - fix(mobile): hide latest version if disabled by [@uhthomas](https://github.com/uhthomas) in [#25691](immich-app/immich#25691) - fix(web): enable asset viewer navigation across memory boundaries by [@midzelis](https://github.com/midzelis) in [#25741](immich-app/immich#25741) - fix: upload progress bar flickering by [@alextran1502](https://github.com/alextran1502) in [#25829](immich-app/immich#25829) - fix: prevent stale values in edit user form after save by [@michelheusschen](https://github.com/michelheusschen) in [#25859](immich-app/immich#25859) - fix: prevent album page get rebuilt when resuming app by [@alextran1502](https://github.com/alextran1502) in [#25862](immich-app/immich#25862) - fix: prevent backspace from accidentally triggering delete modals by [@michelheusschen](https://github.com/michelheusschen) in [#25858](immich-app/immich#25858) - fix: metadata extraction race condition by [@danieldietzler](https://github.com/danieldietzler) in [#25866](immich-app/immich#25866) - fix: reset zoom when navigating between assets by [@michelheusschen](https://github.com/michelheusschen) in [#25863](immich-app/immich#25863) ##### 📚 Documentation - docs(openapi): Add descriptions to OpenAPI specification by [@timonrieger](https://github.com/timonrieger) in [#25185](immich-app/immich#25185) - fix(docs): clarify supported vector version by [@mmomjian](https://github.com/mmomjian) in [#25753](immich-app/immich#25753) **Full Changelog**: <immich-app/immich@v2.5.2...v2.5.3> </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Enabled. ♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Reviewed-on: https://gitea.alexlebens.dev/alexlebens/infrastructure/pulls/3705 Co-authored-by: Renovate Bot <renovate-bot@alexlebens.net> Co-committed-by: Renovate Bot <renovate-bot@alexlebens.net>

This PR contains the following updates: | Package | Update | Change | |---|---|---| | [ghcr.io/immich-app/immich-machine-learning](https://github.com/immich-app/immich) | minor | `v2.4.1` → `v2.5.5` | | [ghcr.io/immich-app/immich-server](https://github.com/immich-app/immich) | minor | `v2.4.1` → `v2.5.5` | --- > ⚠️ **Warning** > > Some dependencies could not be looked up. Check the Dependency Dashboard for more information. --- ### Release Notes <details> <summary>immich-app/immich (ghcr.io/immich-app/immich-machine-learning)</summary> ### [`v2.5.5`](https://github.com/immich-app/immich/releases/tag/v2.5.5) [Compare Source](immich-app/immich@v2.5.3...v2.5.5) ##### v2.5.5 *`v2.5.4` was in the way of getting out, and we got another annoyance bug fixed, so we rolled it into `v2.5.5`* Happy Friday! This release addresses more bugs from the `v2.5.0` release. Enjoy! - Fixed an issue where changing the timezone on the web changes the time instead of the timezone - Fixed an issue where background task on iOS don't get triggered as often - Fixes some issues regarding the usage of self-signed certificate and mLTS on the mobile app ##### 🐛 Bug fixes - fix(mobile): cancel share download when dialog is dismissed by [@cmdPromptCritical](https://github.com/cmdPromptCritical) in [#25466](immich-app/immich#25466) - fix: album dto docs by [@jrasm91](https://github.com/jrasm91) in [#25873](immich-app/immich#25873) - fix: null validation by [@jrasm91](https://github.com/jrasm91) in [#25891](immich-app/immich#25891) - fix(server): deleting stacked assets by [@jrasm91](https://github.com/jrasm91) in [#25874](immich-app/immich#25874) - fix: close tag modal after tagging assets by [@michelheusschen](https://github.com/michelheusschen) in [#25884](immich-app/immich#25884) - fix: correctly sync shared link download with metadata toggle by [@michelheusschen](https://github.com/michelheusschen) in [#25885](immich-app/immich#25885) - fix: date time picker text color in dark mode by [@alextran1502](https://github.com/alextran1502) in [#25883](immich-app/immich#25883) - fix: allow null tagIds in search dto by [@michelheusschen](https://github.com/michelheusschen) in [#25920](immich-app/immich#25920) - fix: improve asset editor exit handling by [@michelheusschen](https://github.com/michelheusschen) in [#25917](immich-app/immich#25917) - fix: make switch labels properly clickable by [@michelheusschen](https://github.com/michelheusschen) in [#25898](immich-app/immich#25898) - fix: ensure theme stays in sync with [@immich/ui](https://github.com/immich/ui) by [@michelheusschen](https://github.com/michelheusschen) in [#25922](immich-app/immich#25922) - fix: preserve hidden people state across pagination by [@michelheusschen](https://github.com/michelheusschen) in [#25886](immich-app/immich#25886) - fix: file name search label by [@alextran1502](https://github.com/alextran1502) in [#25916](immich-app/immich#25916) - fix(mobile): mtls on native clients by [@mertalev](https://github.com/mertalev) in [#25802](immich-app/immich#25802) - fix: time zone upserts by [@danieldietzler](https://github.com/danieldietzler) in [#25889](immich-app/immich#25889) - fix(web): Ensure profile picture is cropped to 1:1 ratio by [@aditya-ai-architect](https://github.com/aditya-ai-architect) in [#25892](immich-app/immich#25892) - fix(mobile): reset asset index on timeline refresh by [@uhthomas](https://github.com/uhthomas) in [#25729](immich-app/immich#25729) - fix: timezone in timeline bucketing by [@shenlong-tanwen](https://github.com/shenlong-tanwen) in [#25894](immich-app/immich#25894) - fix(mobile): Update preview and PageController position when the asset count decreases while the last item is selected by [@PeterOmbodi](https://github.com/PeterOmbodi) in [#25563](immich-app/immich#25563) - fix(server): use provided database username for restore & ensure name is not mangled by [@insertish](https://github.com/insertish) in [#25679](immich-app/immich#25679) - fix: image download complete notification shows an extra {file\_name} template tag by [@romoisverycool](https://github.com/romoisverycool) in [#25936](immich-app/immich#25936) - fix: face and edit handling by [@bwees](https://github.com/bwees) in [#25738](immich-app/immich#25738) - fix: queue assets missing fullsize files for thumbnail regeneration by [@midzelis](https://github.com/midzelis) in [#25794](immich-app/immich#25794) - fix: dedupe version announcement modal by [@jrasm91](https://github.com/jrasm91) in [#25946](immich-app/immich#25946) - fix(cli): suppress startup messages for immich-admin by [@VahantSharma](https://github.com/VahantSharma) in [#25928](immich-app/immich#25928) ##### 📚 Documentation - docs: update manual backup/restore to match the automatic process by [@insertish](https://github.com/insertish) in [#25924](immich-app/immich#25924) - fix(docs): add missing --json-output arg to CLI example by [@Xiol](https://github.com/Xiol) in [#25870](immich-app/immich#25870) - docs: remove writeTimeout on traefik example by [@kaysond](https://github.com/kaysond) in [#25837](immich-app/immich#25837) ##### 🌐 Translations - chore(web): update translations by [@weblate](https://github.com/weblate) in [#25585](immich-app/immich#25585) ##### New Contributors - [@aditya-ai-architect](https://github.com/aditya-ai-architect) made their first contribution in [#25892](immich-app/immich#25892) - [@VahantSharma](https://github.com/VahantSharma) made their first contribution in [#25927](immich-app/immich#25927) - [@Xiol](https://github.com/Xiol) made their first contribution in [#25870](immich-app/immich#25870) - [@cmdPromptCritical](https://github.com/cmdPromptCritical) made their first contribution in [#25466](immich-app/immich#25466) - [@romoisverycool](https://github.com/romoisverycool) made their first contribution in [#25936](immich-app/immich#25936) - [@didekoning](https://github.com/didekoning) made their first contribution in [#25937](immich-app/immich#25937) **Full Changelog**: <immich-app/immich@v2.5.3...v2.5.5> ### [`v2.5.3`](https://github.com/immich-app/immich/releases/tag/v2.5.3) [Compare Source](immich-app/immich@v2.5.2...v2.5.3) ##### What's Changed ##### 🐛 Bug fixes - chore: remove random code snippet by [@jrasm91](https://github.com/jrasm91) in [#25677](immich-app/immich#25677) - fix: reset and unsaved change states in editor by [@bwees](https://github.com/bwees) in [#25588](immich-app/immich#25588) - fix: no notification if release check is disabled by [@jrasm91](https://github.com/jrasm91) in [#25688](immich-app/immich#25688) - fix(mobile): hide latest version if disabled by [@uhthomas](https://github.com/uhthomas) in [#25691](immich-app/immich#25691) - fix(web): enable asset viewer navigation across memory boundaries by [@midzelis](https://github.com/midzelis) in [#25741](immich-app/immich#25741) - fix: upload progress bar flickering by [@alextran1502](https://github.com/alextran1502) in [#25829](immich-app/immich#25829) - fix: prevent stale values in edit user form after save by [@michelheusschen](https://github.com/michelheusschen) in [#25859](immich-app/immich#25859) - fix: prevent album page get rebuilt when resuming app by [@alextran1502](https://github.com/alextran1502) in [#25862](immich-app/immich#25862) - fix: prevent backspace from accidentally triggering delete modals by [@michelheusschen](https://github.com/michelheusschen) in [#25858](immich-app/immich#25858) - fix: metadata extraction race condition by [@danieldietzler](https://github.com/danieldietzler) in [#25866](immich-app/immich#25866) - fix: reset zoom when navigating between assets by [@michelheusschen](https://github.com/michelheusschen) in [#25863](immich-app/immich#25863) ##### 📚 Documentation - docs(openapi): Add descriptions to OpenAPI specification by [@timonrieger](https://github.com/timonrieger) in [#25185](immich-app/immich#25185) - fix(docs): clarify supported vector version by [@mmomjian](https://github.com/mmomjian) in [#25753](immich-app/immich#25753) **Full Changelog**: <immich-app/immich@v2.5.2...v2.5.3> ### [`v2.5.2`](https://github.com/immich-app/immich/releases/tag/v2.5.2) [Compare Source](immich-app/immich@v2.5.0...v2.5.2) ##### v2.5.2 *`v2.5.1` has been sacrificed for the release God, so the Android app can now be released* > \[!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 ##### Hotfixes - Fixed a bug where the video aspect ratio is played incorrectly for the remote asset - Fixed a bug where memory generation failed - Fixed a bug where memories don't show on the web until the page is refreshed - Fixed a bug where the `Load original image` option doesn't render the image on iOS ##### What's Changed ##### 🐛 Bug fixes - fix: deleting asset from asset-viewer on search results by [@midzelis](https://github.com/midzelis) in [#25596](immich-app/immich#25596) - fix: escape handling in search asset viewer by [@danieldietzler](https://github.com/danieldietzler) in [#25621](immich-app/immich#25621) - fix: correctly show owner in album options modal by [@danieldietzler](https://github.com/danieldietzler) in [#25618](immich-app/immich#25618) - fix(server): don't assume maintenance action is set by [@insertish](https://github.com/insertish) in [#25622](immich-app/immich#25622) - fix: album card ranges by [@danieldietzler](https://github.com/danieldietzler) in [#25639](immich-app/immich#25639) - fix(mobile): show controls by default on motion photos by [@goalie2002](https://github.com/goalie2002) in [#25638](immich-app/immich#25638) - fix: escape handling by [@danieldietzler](https://github.com/danieldietzler) in [#25627](immich-app/immich#25627) - fix(mobile): set correct system-ui mode on asset viewer init by [@goalie2002](https://github.com/goalie2002) in [#25610](immich-app/immich#25610) - fix(mobile): actually load original image by [@mertalev](https://github.com/mertalev) in [#25646](immich-app/immich#25646) - fix: width and height migration issue by [@alextran1502](https://github.com/alextran1502) in [#25643](immich-app/immich#25643) - fix: memory lane by [@jrasm91](https://github.com/jrasm91) in [#25652](immich-app/immich#25652) - fix: memory generation by [@jrasm91](https://github.com/jrasm91) in [#25650](immich-app/immich#25650) - fix(mobile): tall image scrolling by [@ByteSizedMarius](https://github.com/ByteSizedMarius) in [#25649](immich-app/immich#25649) **Full Changelog**: <immich-app/immich@v2.5.0...v2.5.2> ### [`v2.5.0`](https://github.com/immich-app/immich/releases/tag/v2.5.0): - 90000 Stars Release [Compare Source](immich-app/immich@v2.4.1...v2.5.0) ##### v2.5.0 > \[!NOTE] > > ### 01/27 > > - 20:23 GMT: We are halting the release of the mobile app as there are some reported issues with migration > - 22:00 GMT: Found the issue with the migration for the experimental sync-delete feature on Android. Will fix and release a new update soon. ETA tomorrow CTS time > - 22:24 GMT: iOS is released as the migration doesn't affect iOS users > > ### 01/28 > > - Discovered some annoyance bugs regarding editing after ready to release `v2.5.1`, so spent the whole day fixing them and will release `v2.5.2` on Thursday (01/29) > > Sorry for the inconvenience ##### Highlights Happy New Year! Welcome to Immich `v2.5.0`. This release is our fireworks to celebrate both the new year and reaching *90,000* stars on GitHub. It is packed with major features that have been in the works for quite some time, and the team has kicked off the year with incredible momentum that we're excited to carry forward. We couldn't wait to share this with you. Let's dive right in: - Free Up Space - Non-destructive editing - Database backup and restore (web) - Upload improvements - Visual refresh across all platforms - Disable admin setup - Star rating (mobile) - Additional fine-grained permissions (api keys) - Progressive JPEGs - Slideshow loop option (web) - Native HTTP clients for HTTP/2 and HTTP/3 image loading ##### Free Up Space *This feature was requested ages ago. So long in fact, that it has a 3-digit ID ([#165](immich-app/immich#165))! Given the rapid iteration and development pace of the pre-stable era, it was risky to include it in the app due to its bulk-delete nature. But it is now 2026* 😄*, so here we are.* **Free Up Space** allows you to remove local media files from your device that have already been successfully backed up to your Immich server (and are not in Immich trash). This helps reclaim storage on your mobile device without losing your memories. The feature can be accessed from the user profile panel or from the Settings page in the mobile app. <img width="300" alt="image" src="https://github.com/user-attachments/assets/2985ea6c-4392-414e-aef3-83c70ffe5570" /> <img alt="image" src="https://github.com/user-attachments/assets/cf7b7d2c-5d37-4c13-a6ad-cacb53a71acb" /> There are configuration options and steps to make sure that everything is verified before deleting from the app. 1. **Configuration:** - **Cutoff date:** Free Up Space will only look for photos and videos **on or before** this date. - **Keep albums:** Hold all photos and videos in the selected albums on your device, regardless of other settings. By default, `**WhatsApp**` related albums are selected to be kept on the device. Assets that are not already on the device will not be redownloaded. - **Keep favorites:** This works the same way `**Keep albums**` . By default, favorited assets are preserved on your device. - **Keep on device:** You can choose to restrict removal to `**Always keep**` **All photos** or **All videos**, regardless of other settings. This setting can hamper freeing up space significantly — with 80 GB of videos and 40 GB of photos, selecting `**Always keep photos**` retains thousands of photos on your device. > \[!TIP] > These configurations are persistent to make it convenient for those who perform this task often. 2. **Scan & Review:** Before any files are removed, you are presented with a review screen to confirm which items will be deleted and how much storage will be reclaimed. 3. **Deletion:** Confirmed items are moved to your device's native Trash/Recycle Bin. > \[!NOTE] > **Reclaim storage** > To use the reclaimed space right away, you must manually empty the system/gallery trash outside Immich. For more information about this feature, please read it [here](https://docs.immich.app/features/mobile-app#free-up-space) ##### Non-destructive editing Immich now supports non-destructive photo editing. This means that any edits you make to an asset do not modify the original file; instead, the modifications are stored in the database, and new thumbnails are generated based on those changes. This means you can always revert to the original asset if needed. When you download an edited asset, Immich provides the edited version by default. However, you can choose to download the original version if needed. Immich always generates an edited full-size version based on your full-size quality settings. This occurs regardless of whether the "Enable full-size image generation" setting is enabled or disabled. > \[!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. You can click on the following icon to enter edit mode <img width="400" alt="image" src="https://github.com/user-attachments/assets/7f2092cf-c149-492c-af08-a04c8de16915" /> Currently, Immich supports the following types of edits: - Cropping - Rotation - Mirroring <img width="800" alt="image" src="https://github.com/user-attachments/assets/b1c0b1e7-5074-4b19-ac23-449931a233f3" /> Opening the editor on an edited asset will load the existing edits back in so you can make adjustments and changes. <img width="800" alt="image" src="https://github.com/user-attachments/assets/0346e1ac-eb8c-490a-8d47-a3b79626b5b6" /> ##### Backup and restore from the web UI Backup and restore are an important part of any self-hosted application; this feature helps you maintain reliable access to your instance during unexpected events, such as database corruption caused by system failure or power loss. Historically, restoring an Immich instance to a specific point required the user to have access to the command line, which proved challenging for many users, especially those new to self-hosting and software maintenance. Now, we have the entire backup and restore pipeline built into Immich, which allows you to quickly restore a database backup directly from the web UI. You can perform the steps either from the `Administration > Maintenance` page, or from a brand new instance on the welcome page. **Restore from Administration's Maintenance page** <img width="800" alt="image" src="https://github.com/user-attachments/assets/7a608442-bd1c-4e0c-b255-1df45699fa9f" /> **Restore from Onboarding page** <img width="800" alt="image" src="https://github.com/user-attachments/assets/6012a0e6-ba32-45d0-aec4-c24d19bd4a25" /> For more detailed steps, please read them in [our documentation](https://docs.immich.app/administration/backup-and-restore) ##### Upload improvement This release also improves foreground upload in the mobile app. The previous implementation improves background uploads but leaves foreground uploads less reliable by leveraging the queue system to offload upload handling to the OS, which can be throttled under specific criteria. We are taking back more control over handling uploads with the *try-and-true* method used in the old timeline, but this time it is supercharged with concurrent uploads and also correctly handles assets with missing file extensions from software such as DJI or Fusion Camera. <img width="300" alt="image" src="https://github.com/user-attachments/assets/87d317ed-933b-48c7-88e3-d267e928b9d1" /> Upload now will also send unique metadata for each asset to the server, so it can be used to quickly retrieve the checksum when reinstalling the app, saving time and CPU resources. This is especially useful for iCloud users, as the hashing process can take a long time. For iOS and iCloud users, it is recommended to go to App Settings > Sync Status and tap the "Sync Cloud IDs" button to backfill the metadata for the uploaded content. You only need to do this once. <img width="300" alt="image" src="https://github.com/user-attachments/assets/0470e707-f913-418c-94a5-3fb83ae95fae" /> ##### Visual refresh across all platforms This release also brings you a refreshed look and feel across the web, mobile app, and the documentation sites, with a new font face ("The-name-must-not-be-named" Sans) that improves reading legibility, especially for numbers and smaller text. <img width="300" alt="image" src="https://github.com/user-attachments/assets/83fc22ab-c3c8-4dfe-99c2-4620c6f03938" /> The UI library (<https://ui.immich.app/>) components have also been added to the web app in more places. You should see a more standardized, coherent, and better hierarchy for UI components across the app. <img width="300" alt="image" src="https://github.com/user-attachments/assets/80157cb0-e77f-4219-9648-373a21ebfd6e" /> All icon buttons now come with a tooltip, so you don't have to guess what function the button serves <img width="300" alt="image" src="https://github.com/user-attachments/assets/df2119dc-d3a9-43ae-a002-593710d3d226" /> ##### Star rating (mobile) Mobile now has the star-rating feature, similar to the web application. If you don't see a star rating on either platform, make sure the feature is enabled [here](https://my.immich.app/user-settings?isOpen=feature+rating). <img width="400" alt="image" src="https://github.com/user-attachments/assets/e6a3e6a4-a18a-41a4-9eb0-845be68904a9" /> ##### Disable admin setup New installs show a welcome page and allow anyone to sign up / register as an admin. To have more control over whether this is allowed or not, we have added the following environment variable: ```typescript IMMICH_ALLOW_SETUP=true|false ``` This is especially useful if you have already initialized Immich and never want this situation to be possible in the future, which can happen if for whatever reason the database is reset. ##### Additional fine-grained permissions (api keys) Some existing endpoints have been assigned fine-grained permissions, allowing the creation of API keys with limited access. The new permissions include:\n - `map.read` - Retrieve a list of latitude and longitude coordinates for every asset with location data - `map.search` - Retrieve location information for latitude & longitude coordinates - `folder.read` - Retrieve information about folders and which assets they contain ##### Progressive JPEGs All image-generation settings now include a new option to enable progressive JPEGs. When enabled, supported browsers will progressively render the image. <img width="800" alt="image" src="https://github.com/user-attachments/assets/ac62bb63-41da-419b-808f-b81ef90f7183" /> ##### Slideshow loop option (web) The slideshow settings on the web now include an option to automatically start the slideshow over. <img width="500" alt="image" src="https://github.com/user-attachments/assets/b9122b7b-ae6f-4536-bf4c-fc295f6bd486" /> ##### Native HTTP clients All remote images are now requested using optimized HTTP clients, meaning images load more quickly and can keep up with your scrolling. Caching is also improved: not only does this make images even snappier to load after being downloaded, it also improves the offline experience with better responsiveness and a larger cache size. *** As always, there are many more QoL improvements, bug fixes, and enhancements in this release. Please find the full release note below ##### Support Immich <p align="center"> <img src="https://media.giphy.com/media/v1.Y2lkPTc5MGI3NjExbjY2eWc5Y2F0ZW56MmR4aWE0dDhzZXlidXRmYWZyajl1bWZidXZpcyZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/87CKDqErVfMqY/giphy.gif" width="450" title="SUPPORT THE PROJECT!"> </p> If you find the project helpful, you can support Immich by purchasing a product key at <https://buy.immich.app> or our merchandise at <https://immich.store>  ##### What's Changed ##### 🚀 Features - feat: workflow ui by [@alextran1502](https://github.com/alextran1502) in [#24190](immich-app/immich#24190) - feat: disable admin setup by [@jrasm91](https://github.com/jrasm91) in [#24628](immich-app/immich#24628) - feat: free up space by [@alextran1502](https://github.com/alextran1502) in [#24999](immich-app/immich#24999) - feat: use fastlane sigh to manage signing profiles by [@alextran1502](https://github.com/alextran1502) in [#25089](immich-app/immich#25089) - feat: image editing by [@bwees](https://github.com/bwees) in [#24155](immich-app/immich#24155) - feat: add cloud id during native sync by [@shenlong-tanwen](https://github.com/shenlong-tanwen) in [#20418](immich-app/immich#20418) - feat: restore database backups by [@insertish](https://github.com/insertish) in [#23978](immich-app/immich#23978) - feat(mobile): star rating by [@YarosMallorca](https://github.com/YarosMallorca) in [#24457](immich-app/immich#24457) - feat(mobile): scrollbar for album page by [@alextran1502](https://github.com/alextran1502) in [#25507](immich-app/immich#25507) ##### 🌟 Enhancements - feat: focus jumped-to item in timeline by [@bo0tzz](https://github.com/bo0tzz) in [#24738](immich-app/immich#24738) - chore: web editor improvements by [@bwees](https://github.com/bwees) in [#25169](immich-app/immich#25169) - feat: modal routes by [@jrasm91](https://github.com/jrasm91) in [#24726](immich-app/immich#24726) - feat: prefer admin settings page over users page by [@jrasm91](https://github.com/jrasm91) in [#24780](immich-app/immich#24780) - feat: shared link edit by [@jrasm91](https://github.com/jrasm91) in [#24783](immich-app/immich#24783) - feat(mobile): use tabular figures in backup info card by [@wrbl606](https://github.com/wrbl606) in [#24820](immich-app/immich#24820) - feat(mobile): album options to kebab menu by [@idubnori](https://github.com/idubnori) in [#24204](immich-app/immich#24204) - feat: Hide/show controls when zoom state changes by [@Lauritz-Tieste](https://github.com/Lauritz-Tieste) in [#24784](immich-app/immich#24784) - feat(server): Support camera `make`, `model`, and `lensModel` in Storage Template by [@rahul-kumar-saini](https://github.com/rahul-kumar-saini) in [#24650](immich-app/immich#24650) - feat(ml): update ONNX Runtime, OpenVINO and ROCm stack by [@savely-krasovsky](https://github.com/savely-krasovsky) in [#23458](immich-app/immich#23458) - chore(server): Vchord 1.0 support by [@mmomjian](https://github.com/mmomjian) in [#23845](immich-app/immich#23845) - feat(web): Add coordinate pair location searching. by [@GustavJones](https://github.com/GustavJones) in [#24799](immich-app/immich#24799) - feat: show asset owners for editors in shared albums by [@ama156](https://github.com/ama156) in [#24890](immich-app/immich#24890) - feat(web): undo delete single asset by [@YarosMallorca](https://github.com/YarosMallorca) in [#24439](immich-app/immich#24439) - feat(server): implement switchable logging formats (console/json) by [@DanielRamosAcosta](https://github.com/DanielRamosAcosta) in [#24791](immich-app/immich#24791) - chore(web): bump immich/ui for tooltips by [@jrasm91](https://github.com/jrasm91) in [#24632](immich-app/immich#24632) - feat(web): star rating keyboard shortcut by [@cbochs](https://github.com/cbochs) in [#24620](immich-app/immich#24620) - feat: bulk asset metadata endpoints by [@jrasm91](https://github.com/jrasm91) in [#25133](immich-app/immich#25133) - feat(mobile): 2026 font by [@alextran1502](https://github.com/alextran1502) in [#25213](immich-app/immich#25213) - feat(web): search albums by description by [@YarosMallorca](https://github.com/YarosMallorca) in [#25244](immich-app/immich#25244) - feat(web): 2026 font by [@alextran1502](https://github.com/alextran1502) in [#25174](immich-app/immich#25174) - chore: dart http foreground upload by [@alextran1502](https://github.com/alextran1502) in [#24883](immich-app/immich#24883) - feat: update intel compute driver by [@savely-krasovsky](https://github.com/savely-krasovsky) in [#25259](immich-app/immich#25259) - feat: download original asset by [@danieldietzler](https://github.com/danieldietzler) in [#25302](immich-app/immich#25302) - feat: allow /memory?id= in AndroidManifest by [@arne182](https://github.com/arne182) in [#25373](immich-app/immich#25373) - fix: add scoped API permissions to map endpoints by [@meesfrensel](https://github.com/meesfrensel) in [#25423](immich-app/immich#25423) - fix(server): scoped permissions for more endpoints by [@meesfrensel](https://github.com/meesfrensel) in [#25452](immich-app/immich#25452) - feat: generate progressive JPEGs for thumbnails by [@midzelis](https://github.com/midzelis) in [#25463](immich-app/immich#25463) - feat: loop slideshows by [@GeneralZero](https://github.com/GeneralZero) in [#25462](immich-app/immich#25462) - feat(mobile): native clients by [@mertalev](https://github.com/mertalev) in [#21459](immich-app/immich#21459) ##### 🐛 Bug fixes - fix(maintenance): prevent enable/disable maintenance CLI hanging on occasion by [@insertish](https://github.com/insertish) in [#24713](immich-app/immich#24713) - fix(web): display jxl original by [@mertalev](https://github.com/mertalev) in [#24766](immich-app/immich#24766) - fix(web): stale album info by [@jrasm91](https://github.com/jrasm91) in [#24787](immich-app/immich#24787) - fix: album card timezone by [@danieldietzler](https://github.com/danieldietzler) in [#24855](immich-app/immich#24855) - fix(web): let slideshow videos play ([#19601](immich-app/immich#19601)) by [@keanucz](https://github.com/keanucz) in [#24914](immich-app/immich#24914) - fix(server): update exiftool-vendored to v34.3 for correct colon-less timezone parsing by [@dosten](https://github.com/dosten) in [#24979](immich-app/immich#24979) - fix(mobile): hide delete action for remote-only assets by [@skrmc](https://github.com/skrmc) in [#25010](immich-app/immich#25010) - fix: import config from json by [@MontejoJorge](https://github.com/MontejoJorge) in [#25030](immich-app/immich#25030) - fix: search input has incorrect focus state after closing the search filter modal by [@alextran1502](https://github.com/alextran1502) in [#24886](immich-app/immich#24886) - fix(web): duplicate key error and enable expiration editing for expired shared links by [@timonrieger](https://github.com/timonrieger) in [#24686](immich-app/immich#24686) - fix: shared-link-mapper by [@jrasm91](https://github.com/jrasm91) in [#24794](immich-app/immich#24794) - fix(server): migrate motion part of live photo by [@NikhilAlapati](https://github.com/NikhilAlapati) in [#24688](immich-app/immich#24688) - fix(web): use asset date for change date popup when single asset selected by [@majiayu000](https://github.com/majiayu000) in [#25076](immich-app/immich#25076) - fix(web): long text taking more width than expected in duplicate manager by [@HemendraSinghShekhawat](https://github.com/HemendraSinghShekhawat) in [#24547](immich-app/immich#24547) - fix(web): broken asset urls if shared link has photos in name by [@YarosMallorca](https://github.com/YarosMallorca) in [#24451](immich-app/immich#24451) - fix(server): search statistics with personIds returns 500 by [@majiayu000](https://github.com/majiayu000) in [#25074](immich-app/immich#25074) - fix(web): server stats layout by [@meesfrensel](https://github.com/meesfrensel) in [#25085](immich-app/immich#25085) - fix: enter now submits the date modals by [@fabb](https://github.com/fabb) in [#25053](immich-app/immich#25053) - fix(web): improve text contrast in minimized upload panel by [@majiayu000](https://github.com/majiayu000) in [#25075](immich-app/immich#25075) - fix: propagate iCloud Shared Album flag by [@alextran1502](https://github.com/alextran1502) in [#25060](immich-app/immich#25060) - fix: description does not rerender when navigating between assets by [@alextran1502](https://github.com/alextran1502) in [#25137](immich-app/immich#25137) - fix(server): avoid upserting empty metadata array by [@timonrieger](https://github.com/timonrieger) in [#25143](immich-app/immich#25143) - fix(server): Document HTTP 200 response for duplicate uploads in OpenAPI by [@timonrieger](https://github.com/timonrieger) in [#25148](immich-app/immich#25148) - fix(web): person asset count doesn't update when navigating by [@YarosMallorca](https://github.com/YarosMallorca) in [#24438](immich-app/immich#24438) - fix(mobile): remove weird zooming behaviour on videos and play/pause button delay by [@goalie2002](https://github.com/goalie2002) in [#24006](immich-app/immich#24006) - fix: unlock properties after successful sidecar write by [@danieldietzler](https://github.com/danieldietzler) in [#25168](immich-app/immich#25168) - fix(web): show relevant navbar options for partner assets by [@YarosMallorca](https://github.com/YarosMallorca) in [#24832](immich-app/immich#24832) - fix(web): added background gradient for video time visibility by [@HemendraSinghShekhawat](https://github.com/HemendraSinghShekhawat) in [#25138](immich-app/immich#25138) - feat(mobile): do not restore locally deleted assets during trash sync (Android) by [@PeterOmbodi](https://github.com/PeterOmbodi) in [#24218](immich-app/immich#24218) - fix: asset local type casting by [@alextran1502](https://github.com/alextran1502) in [#25214](immich-app/immich#25214) - fix(web): ocr button not clickable for stacked assets by [@YarosMallorca](https://github.com/YarosMallorca) in [#25210](immich-app/immich#25210) - fix(web): Handle upload failures from public users by [@juliancarrivick](https://github.com/juliancarrivick) in [#24826](immich-app/immich#24826) - fix(mobile): prevent system UI from hiding on drag down gesture by [@goalie2002](https://github.com/goalie2002) in [#25240](immich-app/immich#25240) - fix: migration order by [@jrasm91](https://github.com/jrasm91) in [#25249](immich-app/immich#25249) - fix(web): redirect to login by [@jrasm91](https://github.com/jrasm91) in [#25254](immich-app/immich#25254) - fix(mobile): improve asset transition back to timeline by [@goalie2002](https://github.com/goalie2002) in [#24485](immich-app/immich#24485) - fix: dark mode appbar color by [@akashKarmakar02](https://github.com/akashKarmakar02) in [#24976](immich-app/immich#24976) - fix(web): add min-width to setting input field by [@K0lin](https://github.com/K0lin) in [#25317](immich-app/immich#25317) - fix(server): api key update checks by [@jrasm91](https://github.com/jrasm91) in [#25363](immich-app/immich#25363) - fix(mobile): album selector icon visibility by [@ByteSizedMarius](https://github.com/ByteSizedMarius) in [#25311](immich-app/immich#25311) - fix(mobile): indicators not showing on thumbnail tile after asset change in viewer by [@goalie2002](https://github.com/goalie2002) in [#25297](immich-app/immich#25297) - fix(web): handle deletion from asset viewer on map page by [@meesfrensel](https://github.com/meesfrensel) in [#25393](immich-app/immich#25393) - fix: tag update race condition by [@danieldietzler](https://github.com/danieldietzler) in [#25371](immich-app/immich#25371) - fix(web): allow exiting pin setup flow by [@meesfrensel](https://github.com/meesfrensel) in [#25413](immich-app/immich#25413) - fix: upload file without extension by [@alextran1502](https://github.com/alextran1502) in [#25419](immich-app/immich#25419) - fix: incorrect asset viewer scale on image frame update by [@shenlong-tanwen](https://github.com/shenlong-tanwen) in [#25430](immich-app/immich#25430) - fix(mobile): bring back map settings by [@shenlong-tanwen](https://github.com/shenlong-tanwen) in [#25448](immich-app/immich#25448) - fix(web): fix badge value in queues page by [@beinganukul](https://github.com/beinganukul) in [#25445](immich-app/immich#25445) - fix(mobile): backfill asset dimensions to exif table by [@bwees](https://github.com/bwees) in [#25483](immich-app/immich#25483) - fix(mobile): do not try to load video as image by [@mertalev](https://github.com/mertalev) in [#25495](immich-app/immich#25495) ##### 📚 Documentation - fix: product keys wording in commercial guidelines faq by [@bo0tzz](https://github.com/bo0tzz) in [#24765](immich-app/immich#24765) - docs: config options for hardware transcoding by [@Javex](https://github.com/Javex) in [#24853](immich-app/immich#24853) - fix: use my.immich.app as url placeholder in docs by [@bo0tzz](https://github.com/bo0tzz) in [#25153](immich-app/immich#25153) - chore: update Thai README (remove "under active development" lines) by [@ppnplus](https://github.com/ppnplus) in [#25208](immich-app/immich#25208) - fix(docs): add missing mermaid dependency and configuration by [@bdoerfchen](https://github.com/bdoerfchen) in [#25247](immich-app/immich#25247) - chore(docs): update RAM req by [@mmomjian](https://github.com/mmomjian) in [#25344](immich-app/immich#25344) - feat(docs): add Free Up Space section by [@aviv926](https://github.com/aviv926) in [#25253](immich-app/immich#25253) - docs: update README\_de\_DE.md by [@solluh](https://github.com/solluh) in [#25443](immich-app/immich#25443) - fix(docs): document that fullsize thumbnail might redirect to original by [@meesfrensel](https://github.com/meesfrensel) in [#25416](immich-app/immich#25416) - docs: update documentation by [@alextran1502](https://github.com/alextran1502) in [#25440](immich-app/immich#25440) ##### New Contributors - [@wrbl606](https://github.com/wrbl606) made their first contribution in [#24820](immich-app/immich#24820) - [@keanucz](https://github.com/keanucz) made their first contribution in [#24914](immich-app/immich#24914) - [@rahul-kumar-saini](https://github.com/rahul-kumar-saini) made their first contribution in [#24650](immich-app/immich#24650) - [@dosten](https://github.com/dosten) made their first contribution in [#24979](immich-app/immich#24979) - [@GustavJones](https://github.com/GustavJones) made their first contribution in [#24799](immich-app/immich#24799) - [@skrmc](https://github.com/skrmc) made their first contribution in [#25010](immich-app/immich#25010) - [@ama156](https://github.com/ama156) made their first contribution in [#24890](immich-app/immich#24890) - [@DanielRamosAcosta](https://github.com/DanielRamosAcosta) made their first contribution in [#24791](immich-app/immich#24791) - [@NikhilAlapati](https://github.com/NikhilAlapati) made their first contribution in [#24688](immich-app/immich#24688) - [@flpcury](https://github.com/flpcury) made their first contribution in [#24867](https://github.com/immich-app/immich/pull/24867) - [@Javex](https://github.com/Javex) made their first contribution in [#24853](immich-app/immich#24853) - [@majiayu000](https://github.com/majiayu000) made their first contribution in [#25076](immich-app/immich#25076) - [@HemendraSinghShekhawat](https://github.com/HemendraSinghShekhawat) made their first contribution in [#24547](immich-app/immich#24547) - [@cbochs](https://github.com/cbochs) made their first contribution in [#24620](immich-app/immich#24620) - [@fabb](https://github.com/fabb) made their first contribution in [#25053](immich-app/immich#25053) - [@ppnplus](https://github.com/ppnplus) made their first contribution in [#25208](immich-app/immich#25208) - [@juliancarrivick](https://github.com/juliancarrivick) made their first contribution in [#24826](immich-app/immich#24826) - [@bdoerfchen](https://github.com/bdoerfchen) made their first contribution in [#25247](immich-app/immich#25247) - [@akashKarmakar02](https://github.com/akashKarmakar02) made their first contribution in [#24976](immich-app/immich#24976) - [@K0lin](https://github.com/K0lin) made their first contribution in [#25317](immich-app/immich#25317) - [@NAM-MAN](https://github.com/NAM-MAN) made their first contribution in [#25320](https://github.com/immich-app/immich/pull/25320) - [@ByteSizedMarius](https://github.com/ByteSizedMarius) made their first contribution in [#25311](immich-app/immich#25311) - [@arne182](https://github.com/arne182) made their first contribution in [#25373](immich-app/immich#25373) - [@solluh](https://github.com/solluh) made their first contribution in [#25443](immich-app/immich#25443) - [@beinganukul](https://github.com/beinganukul) made their first contribution in [#25445](immich-app/immich#25445) - [@GeneralZero](https://github.com/GeneralZero) made their first contribution in [#25462](immich-app/immich#25462) **Full Changelog**: <immich-app/immich@v2.4.1...v2.5.0> </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about these updates again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Co-authored-by: Renovate Bot <renovate@zarantonello.dev> Co-committed-by: Renovate Bot <renovate@zarantonello.dev>

@LeLunZ

@LeLunZ

timonrieger requested review from danieldietzler and shenlong-tanwen as code owners January 10, 2026 13:48

immich-push-o-matic bot added the 🗄️server label Jan 10, 2026

timonrieger force-pushed the docs/add-openapi-descriptions branch from e399ec7 to 179b194 Compare January 10, 2026 21:20

timonrieger marked this pull request as draft January 11, 2026 13:50

timonrieger mentioned this pull request Jan 23, 2026

docs(openapi): preview for #25185 #25479

Closed

timonrieger force-pushed the docs/add-openapi-descriptions branch 3 times, most recently from 28cbed1 to ba4db65 Compare January 24, 2026 15:32

timonrieger marked this pull request as ready for review January 24, 2026 17:12

timonrieger mentioned this pull request Jan 24, 2026

docs(openapi): add descriptions for query params #25491

Closed

timonrieger force-pushed the docs/add-openapi-descriptions branch from 2860a64 to c90a09b Compare January 27, 2026 11:58

timonrieger commented Jan 27, 2026

View reviewed changes

mobile/openapi/lib/model/people_update_item.dart Show resolved Hide resolved

jrasm91 requested changes Jan 27, 2026

View reviewed changes

timonrieger requested a review from jrasm91 January 27, 2026 16:56

jrasm91 reviewed Jan 27, 2026

View reviewed changes

faces

ecf8957

timonrieger added 9 commits January 28, 2026 00:13

lint

9112b3a

revert nullable type changes

c6553cf

revert int/num type changes

feb1ca9

remove explicit default

2bddf04

readd comment

a699571

lint

6fd269c

pr fixes

5efa9c5

last bits and pieces

d161556

lint and format

0a8d54d

timonrieger force-pushed the docs/add-openapi-descriptions branch from a6f6587 to 0a8d54d Compare January 27, 2026 23:14

timonrieger requested a review from jrasm91 January 28, 2026 00:44

jrasm91 added the changelog:documentation label Jan 28, 2026

jrasm91 and others added 6 commits January 28, 2026 09:14

chore: remove rejected patches

af8562e

fix: deleting asset from asset-viewer on search results (immich-app#2…

c695640

…5596)

fix: escape handling in search asset viewer (immich-app#25621)

ffa481b

fix: correctly show owner in album options modal (immich-app#25618)

6a2fd87

fix: validation issues

b1efe89

fix: validation issues

c8e7a86

jrasm91 force-pushed the docs/add-openapi-descriptions branch from faca074 to c8e7a86 Compare January 28, 2026 19:42

immich-push-o-matic bot added the 🖥️web label Jan 28, 2026

jrasm91 approved these changes Jan 29, 2026

View reviewed changes

jrasm91 merged commit 8db61d3 into immich-app:main Jan 29, 2026
70 of 73 checks passed

timonrieger deleted the docs/add-openapi-descriptions branch January 29, 2026 15:12

jrasm91 mentioned this pull request Feb 4, 2026

fix: null validation #25891

Merged

michelheusschen mentioned this pull request Feb 5, 2026

fix: allow null tagIds in search dto #25920

Merged

meesfrensel mentioned this pull request Feb 26, 2026

refactor: star rating #26357

Merged

		@ApiProperty({ description: 'Activity type', enum: ReactionType })
		@ValidateEnum({ enum: ReactionType, name: 'ReactionType' })

		@ApiPropertyOptional({ description: 'List of permissions', enum: Permission, isArray: true })
		@ValidateEnum({ enum: Permission, name: 'Permission', each: true, optional: true })

Uh oh!

Conversation

timonrieger commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How Has This Been Tested?

Previewing Descriptions

Checklist:

Please describe to which degree, if any, an LLM was used in creating this pull request.

Uh oh!

timonrieger commented Jan 10, 2026

Uh oh!

timonrieger commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

timonrieger commented Jan 11, 2026

Uh oh!

timonrieger commented Jan 13, 2026

Uh oh!

jrasm91 commented Jan 13, 2026

Uh oh!

timonrieger commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

timonrieger commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jrasm91 commented Jan 26, 2026

Uh oh!

timonrieger commented Jan 26, 2026

Uh oh!

jrasm91 commented Jan 26, 2026

Uh oh!

Uh oh!

timonrieger commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timonrieger commented Jan 27, 2026

Uh oh!

jrasm91 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timonrieger commented Jan 10, 2026 •

edited

Loading

timonrieger commented Jan 10, 2026 •

edited

Loading

timonrieger commented Jan 24, 2026 •

edited

Loading

timonrieger commented Jan 24, 2026 •

edited

Loading

timonrieger commented Jan 27, 2026 •

edited

Loading