docs: update documentation (#25440)

* docs: beginning of the year tune up and updates * darker dark * backup information * promote to table of content * Apply suggestions from code review Co-authored-by: Mert <101130780+mertalev@users.noreply.github.com> Co-authored-by: Mees Frensel <33722705+meesfrensel@users.noreply.github.com> * restore and backup * edit * Apply suggestions from code review Co-authored-by: bo0tzz <git@bo0tzz.me> * feedback * more information on mobile Co-authored-by: https://github.com/aviv926 * more information on free up space > > Co-authored-by: jtagcat <git-12dbd862@jtag.cat> * Update docs/docs/features/mobile-app.mdx Co-authored-by: jtagcat <git-12dbd862@jtag.cat> * screenshot and minor tweaks --------- Co-authored-by: Mert <101130780+mertalev@users.noreply.github.com> Co-authored-by: Mees Frensel <33722705+meesfrensel@users.noreply.github.com> Co-authored-by: bo0tzz <git@bo0tzz.me> Co-authored-by: jtagcat <git-12dbd862@jtag.cat>
2026-05-23 16:12:30 -04:00 · 2026-01-25 09:45:30 -06:00
parent 2ee903a81c
commit a244d94ac8
92 changed files with 344 additions and 245 deletions
@@ -1,42 +0,0 @@
-# Automatic Backup
-
-Immich supports uploading photos and videos from your mobile device to the server automatically.
-
---
-
-You can enable the settings by accessing the upload options from the upload page
-
-<img src={require('./img/backup-settings-access.webp').default} width="50%" title="Backup option selection" />
-
-<img src={require('./img/background-foreground-backup.webp').default} width="50%" title="Foreground&Background Backup" />
-
-## Foreground backup
-
-If foreground backup is enabled: whenever the app is opened or resumed, it will check if any photos or videos in the selected album(s) have yet to be uploaded to the cloud (the remainder count). If there are any, they will be uploaded.
-
-## Background backup
-
-This feature is intended for everyday use. For initial bulk uploading, please use the foreground upload feature. For more information on why background upload is not working as expected, please refer to the [FAQ](/FAQ#why-does-foreground-backup-stop-when-i-navigate-away-from-the-app-shouldnt-it-transfer-the-job-to-background-backup).
-
-If background backup is enabled. The app will periodically check if there are any new photos or videos in the selected album(s) to be uploaded to the server. If there are, it will upload them to the cloud in the background.
-
-:::info Note
-
-#### General
-
- The app must be in the background for the backup worker to start running.
- If you reopen the app and the first page you see is the backup page, the counts will not reflect the background uploaded result. You have to navigate out of the page and come back to see the updated counts.
-
-#### Android
-
- It is a well-known problem that some Android models are very strict with battery optimization settings, which can cause a problem with the background worker. Please visit [Don't kill my app](https://dontkillmyapp.com/) for a guide on disabling this setting on your phone.
-
-#### iOS
-
- You must enable **Background App Refresh** for the app to work in the background. You can enable it in the Settings app under General > Background App Refresh.
-
-<div style={{textAlign: 'center'}}>
-<img src={require('./img/background-app-refresh.webp').default} width="30%" title="background-app-refresh" />
-</div>
-
-:::
@@ -188,6 +188,8 @@ immich upload --dry-run . | tail -n +6 | jq .newFiles[]

 ### Obtain the API Key

-The API key can be obtained in the user setting panel on the web interface.
+The API key can be obtained in the user setting panel on the web interface. You can also specify permissions for the key to limit its access.

 ![Obtain Api Key](./img/obtain-api-key.webp)
+
+![Specify permissions for the key](./img/obtain-api-key-2.webp)
@@ -0,0 +1,19 @@
+# Editing
+
+Immich supports non-destructive editing of photos. This means that any edits you make to an asset do not modify the original file, but instead create a new version of the asset with the edits applied. You can always revert back to the original asset if needed.
+
+## Supported Edits
+
+Currently, Immich supports the following types of edits:
+
+- Cropping
+- Rotation
+- Mirroring
+
+<img src={require('./img/web-edit-interface.webp').default} title="Web edit interface" />
+
+## Download
+
+When you download an edited asset, Immich provides the edited version of the asset by default. However, you can choose to download the original version if needed.
+
+<img src={require('./img/web-edit-download.webp').default} title="Web edit download" />
@@ -21,14 +21,14 @@ The asset detail view will also show the faces that are recognized in the asset.
 Additional actions you can do include:

 - Changing the feature photo of the person
- Setting a person's date of birth
- Merging two or more detected faces into one person
 - Hiding the faces of a person from the Explore page and detail view
- Assigning an unrecognized face to a person
+- Setting a person's date of birth, so that the age of the person can be shown at the time the photo was taken
+- Merging two or more detected people into one person
+- Favoriting a person to pin them to the top of the list

 It can be found from the app bar when you access the detail view of a person.

-<img src={require('./img/facial-recognition-4.webp').default} title='Facial Recognition 4' width="70%"/>
+<img src={require('./img/facial-recognition-4.webp').default} title='Facial Recognition 4' />

 ## How Face Detection Works

@@ -118,46 +118,35 @@ _Remember to run `docker compose up -d` to register the changes. Make sure you c

 These actions must be performed by the Immich administrator.

- Click on your avatar in the upper right corner
- Click on Administration -> External Libraries
- Click on Create an external library…
- Select which user owns the library, this can not be changed later
- Enter `/mnt/media/christmas-trip` then click Add
- Click on Save
- Click the drop-down menu on the newly created library
- Click on Scan
- Click the drop-down menu on the newly created library
- Click on Rename Library and rename it to "Christmas Trip"
+- Click on your avatar in the upper right corner.
+- Click on `Administration -> External Libraries`.
+- Click on `Create Library`.
+- Select which user owns the library, this **can not** be changed later
+- You are now entering the library management page.
+- Click on `Add` in the `Folders` section.
+- Enter `/mnt/media/christmas-trip` then click Add.
+- Click on `Edit` Library and rename it to "Christmas Trip".

 NOTE: We have to use the `/mnt/media/christmas-trip` path and not the `/mnt/nas/christmas-trip` path since all paths have to be what the Docker containers see.

 Next, we'll add an exclusion pattern to filter out raw files.

- Click the drop-down menu on the newly-created Christmas library
- Click on Manage
- Click on Scan Settings
- Click on Add Exclusion Pattern
- Enter `**/Raw/**` and click save.
- Click save
- Click the drop-down menu on the newly created library
- Click on Scan
+- Click on `Add` in the `Exclusion Patterns` section.
+- Enter `**/Raw/**` and click Add.
+- Click on `Scan`

 The christmas trip library will now be scanned in the background. In the meantime, let's add the videos and old photos to another library.

- Click on Create External Library.
-
-:::note
-If you get an error here, please rename the other external library to something else. This is a bug that will be fixed in a future release.
-:::
-
- Click the drop-down menu on the newly created library
- Click Edit Import Paths
- Click on Add Path
+- Go back to `Administration -> External Libraries`.
+- Click on `Create Library`.
+- Select which user owns the library,
+- You are now entering the library management page.
+- Click on `Add` in the `Folders` section.
 - Enter `/mnt/media/old-pics` then click Add
- Click on Add Path
+- Click on `Add` in the `Folders` section.
 - Enter `/mnt/media/videos` then click Add
- Click Save
- Click on Scan
+- Click on `Scan`
+- Click on `Edit` Library and rename it to "Old videos and photos".

 Within seconds, the assets from the old-pics and videos folders should show up in the main timeline.

@@ -20,14 +20,6 @@ Below are the SHA-256 fingerprints for the certificates signing the android appl

 :::

-:::info Beta Program
-The beta release channel allows users to test upcoming changes before they are officially released. To join the channel use the links below.
-
- Android: Invitation link from [web](https://play.google.com/store/apps/details?id=app.alextran.immich) or from [mobile](https://play.google.com/store/apps/details?id=app.alextran.immich)
- iOS: [TestFlight invitation link](https://testflight.apple.com/join/1vYsAa8P)
-
-:::
-
 ## Login

 <MobileAppLogin />
@@ -36,15 +28,11 @@ The beta release channel allows users to test upcoming changes before they are o

 <MobileAppBackup />

-:::info
-You can enable automatic backup on supported devices. For more information see [Automatic Backup](/features/automatic-backup.md).
-:::
-
 ## Sync only selected photos

 If you have a large number of photos on the device, and you would prefer not to backup all the photos, then it might be prudent to only backup selected photos from device to the Immich server.

-First, you need to enable the Storage Indicator in your app's settings. Navigate to **<ins>Settings -> Photo Grid</ins>** and enable **"Show Storage indicator on asset tiles"**; this makes it easy to distinguish local-only assets and synced assets.
+First, you need to enable the Storage Indicator in your app's settings. Navigate to **<ins>Settings -> Photo Grid</ins>** and enable **`Show Storage indicator on asset tiles`**; this makes it easy to distinguish local-only assets and synced assets.

 :::note

@@ -55,13 +43,8 @@ This will enable a small cloud icon on the bottom right corner of the asset tile

 :::

-Now make sure that the local album is selected in the backup screen (steps 1-2 above). You can find these albums listed in **<ins>Library -> On this device</ins>**. To selectively upload photos from these albums, simply select the local-only photos and tap on "Upload" button in the dynamic bottom menu.
+Now make sure that the local album is selected in the backup screen (steps 1-2 above). You can find these albums listed in **<ins>Library -> On this device</ins>**. To selectively upload photos from these albums, simply select the local-only photos and tap on the `Upload` button in the dynamic bottom menu.

-<img
-  src={require('./img/mobile-upload-open-photo.webp').default}
-  width="50%"
-  title="Upload button on local asset preview"
-/>
 <img
  src={require('./img/mobile-upload-selected-photos.webp').default}
  width="40%"
@@ -70,53 +53,46 @@ Now make sure that the local album is selected in the backup screen (steps 1-2 a

 ## Free Up Space

-The **Free Up Space** tool 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 the Immich trash). This helps reclaim storage on your mobile device without losing your memories.
+**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.

 ### How it works

+<img src={require('./img/free-up-space.webp').default} title="Free up space" />
+
 1.  **Configuration:**
-    - **Cutoff Date:** You can select a cutoff date. The tool will only look for photos and videos **on or before** this date.
-    - **Filter Options:** You can choose to remove **All** assets, or restrict removal to **Photos only** or **Videos only**.
-    - **Keep Favorites:** By default, local assets marked as favorites are preserved on your device, even if they match the cutoff date.
-2.  **Scan & Review:** Before any files are removed, you are presented with a review screen to verify which items will be deleted.
-3.  **Deletion:** Confirmed items are moved to your device's native Trash/Recycle Bin. They will be permanently removed by the OS based on your system settings (usually after 30 days).
+    - **Cutoff date:** Free Up Space will only look for photos and videos **on or before** this date. Photos removed from the device don't show up in other (messaging) apps and have to be shared from Immich in order to send them.
+    - **Keep favorites:** This works the same way `Keep albums` does. By default, favorited assets are preserved on your device.
+    - **Keep albums:** Hold all photos and videos in the selected albums on your device, regardless of other settings. By default, `WhatsApp` [related albums](#external-app-dependencies) are selected to be kept on the device. Assets not already on the device will not be re-downloaded.
+    - **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 photos, selecting `Always keep photos` retains thousands of photos on your device.

-:::info Android Permissions
-For the smoothest experience on Android, you should grant Immich special delete privileges. Without this, you may be prompted to confirm deletion for every single image.
+2.  **Scan & Review:** Before any files are removed, you are presented with a review screen to verify which items will be deleted and how much storage is reclamable.
+3.  **Deletion:** Confirmed items are moved to your device's native Trash/Recycle Bin.

-Go to **Immich Settings > Advanced** and enable **"Media Management Access"**.
+:::info reclaim storage
+To use the reclaimed space right away, you must empty the system/gallery trash manually outside of Immich.
 :::

-### iCloud Photos (iOS Users)
+Provided the server is healthy and [backed up](/administration/backup-and-restore.md), assets removed by Free Up Space can always be accessed in the Immich app.

-If you use **iCloud Photos** alongside Immich, it is vital to understand how deletion affects your data. iCloud utilizes a two-way sync; this means deleting a photo from your iPhone to free up space will **also delete it from iCloud**.
+### iCloud Photos
+
+If you use **iCloud Photos** alongside Immich, it is vital to understand how deletion affects your data. After using **Free Up Space**, the photo will be stored **only** on your Immich server (and your phone's "Recently Deleted" folder for 30 days).
+
+Assets that are part of an **iCloud Shared Album** are automatically excluded from the cleanup scan because iCloud does not allow removing the items in Shared Album from the device.

 :::warning iCloud & Backups
-If you rely on iCloud as a secondary backup (part of a 3-2-1 backup strategy), using the Free Up Space feature in Immich will remove the file from both your phone and iCloud.
+If, in addition to Immich, you rely on iCloud as a secondary backup (as part of your [3-2-1](https://www.backblaze.com/blog/the-3-2-1-backup-strategy/) backup strategy), you should instead use `Optimize iPhone Storage` in [iCloud Photos](https://support.apple.com/en-us/105061).

-Once deleted, the photo will exist **only** on your Immich server (and your phone's "Recently Deleted" folder for 30 days).
-
-When you use iCloud Photos and delete a photo or video on one device, it's also deleted on all other devices where you're signed in with the same Apple Account.
-
-More information on the [Apple Support](https://support.apple.com/en-us/108922#iCloud_photo_library) website
-
-**Shared Albums**
-Assets that are part of an **iCloud Shared Album** are automatically excluded from the cleanup scan to ensure they remain viewable to others in the shared album.
+iCloud utilizes a two-way sync; this means deleting a photo, or using Free Up Space from your iPhone will **also delete it from iCloud** and all other devices (Mac, iPad) where you're signed in with the same Apple Account. See [Apple Support](https://support.apple.com/en-us/108922#iCloud_photo_library) for more info.
 :::

-### External App Dependencies (WhatsApp, etc.)
+### External App Dependencies (WhatsApp, etc.) \{#external-app-dependencies\}

-:::danger WhatsApp & Local Files
 Android applications like **WhatsApp** rely on local files to display media in chat history.

 If Immich backs up your WhatsApp folder and you run **Free Up Space**, the local copies of these images will be deleted. Consequently, **media in your WhatsApp chats will appear blurry or missing.** You will only be able to view these photos inside the Immich app; they will no longer be visible within the WhatsApp interface.

-**Recommendation:** If keeping chat history intact is important, please ensure you review the deletion list carefully or consider excluding WhatsApp folders from the backup if you intend to use this feature frequently.
-:::
-
-:::info reclaim storage
-You must empty the system/gallery trash manually to reclaim storage.
-:::
+**Recommendation:** If keeping chat history intact is important, exclude WhatsApp with `Keep albums` in Free Up Space and review the deletion list carefully. You have to enable [Album Sync](#album-sync) for WhatsApp to show up in the list. Alternatively, don't [back up](#backup) WhatsApp with Immich.

 ## Album Sync

@@ -138,10 +114,19 @@ You can sync or mirror an album from your phone to the Immich server on your acc

 ### Synchronizing albums from the past

-Albums can be synchronized to the server even if they did not exist on the server before. In order to apply this setting you have to:  
-Enter the cloud on the top right -> cog wheel on the top right -> select the sync option under Sync albums.
+<img src={require('./img/backup-album-sync.webp').default} width="400px" title="Backup album synchronization option" />
+
+Albums can be synchronized to the server even if they did not exist on the server before. You can enable this feature at any time and use the **Reorganize into album** button to backfill existing uploads into their corresponding albums.

 :::info Sync albums delete/move photos
 If you delete/move photos in the local album on your device, it will not be reflected in the album on the server **even if** you click Sync albums
 It will only reflect files you add.
 :::
+
+## Read-only/kid Mode
+
+You can set the app to read-only mode to prevent accidental deletion of photos from your device, and only allow viewing photos on the timeline.
+
+To toggle this feature, long-press the profile icon or go to `Settings > Advanced > Read-only Mode`.
+
+<img src={require('./img/read-only-mode.webp').default} width="800px" title="Read-only mode" />
@@ -0,0 +1,85 @@
+---
+sidebar_position: 1
+---
+
+# Mobile Backup
+
+## Overview
+
+Immich supports uploading photos and videos from your mobile device to the server automatically.
+
+When backup is enabled, Immich will upload new photos and videos from selected albums when you open or resume the app, as well as periodically in the background.
+
+<img
+src={require('./img/enable-backup-button.webp').default}
+width="400px"
+title="Upload button"
+/>
+
+## General Features
+
+### Backup albums selection
+
+<img
+src={require('./img/backup-album-selection.webp').default}
+width="400px"
+title="Backup album selection"
+/>
+
+You can select which albums on your mobile device to back up to the server. You can also exclude specific albums (by double-tapping on them) from being backed up. This is useful for iOS users since assets can belong to multiple albums. For example, you may want to back up all assets except those in the "Videos" album.
+
+### Deduplication
+
+When you first select albums for backup, Immich calculates a checksum for each file's content. This checksum identifies assets already on the server—whether uploaded via CLI, web interface, or another device. Files matching existing assets are skipped, preventing duplicate uploads and saving bandwidth.
+
+### Networking requirements
+
+By default, Immich will only upload photos and videos when connected to Wi-Fi. You can change this behavior in the backup settings page.
+
+<img
+src={require('./img/backup-options.webp').default}
+width="400px"
+title="Upload button"
+/>
+
+### Backup album synchronization
+
+<img
+src={require('./img/backup-album-sync.webp').default}
+width="400px"
+title="Backup album synchronization option"
+/>
+
+When enabled, Immich automatically creates albums on the server that mirror the albums on your mobile device. Photos and videos are organized into these server-side albums to match your device's album structure, making it easy to find and browse your content the same way you do on your phone.
+
+This is a one-way sync from your device to the server. You can enable this feature at any time and use the **Reorganize into album** button to backfill existing uploads into their corresponding albums.
+
+## Platform Specific Features
+
+### Android
+
+<img
+src={require('./img/android-backup-options.webp').default}
+width="400px"
+title="Android backup options"
+/>
+
+- It is a well-known problem that some Android models are very strict with battery optimization settings, which can cause a problem with the background worker. Please visit [Don't kill my app](https://dontkillmyapp.com/) for a guide on disabling this setting on your phone.
+- You can allow the background task to run only when the device is charging.
+- You can set the minimum delay from the time a photo is taken to when the background upload task will run.
+
+### iOS
+
+- You must enable **Background App Refresh** for the app to work in the background. You can enable it in the Settings app under General > Background App Refresh.
+
+<div style={{textAlign: 'center'}}>
+<img src={require('./img/background-app-refresh.webp').default} width="30%" title="background-app-refresh" />
+</div>
+
+- iOS automatically manages background tasks; the app cannot control when the background upload task will run. The more frequently you open the app, the more often background tasks will run.
+
+#### iCloud Backup
+
+Local albums containing assets from iCloud and marked for backup in Immich will be pulled from iCloud and temporarily stored in the app's cache folder. Once the hashing and uploading process is completed, the temporary files will be emptied.
+
+This process may consume additional data and storage space on your device, especially if you have a large number of iCloud photos and videos. Please ensure you have sufficient storage space and monitor your data usage if you are not connected to Wi-Fi.
@@ -11,45 +11,25 @@ Contextual CLIP search is powered by the [VectorChord](https://github.com/tensor

 In addition, Immich offers advanced search functionality, allowing you to find specific content using customizable search filters. These filters include location, one or more faces, specific albums, and more. You can try out the search filters on the [Demo site](https://demo.immich.app).

-The filters smart search allows you to search by include:
+You can search the following types of content:

- People
- Location
-  - Country
-  - State
-  - City
- Camera
-  - Make
-  - Model
- Date range
- File name or extension
- Media type
-  - Image (including live/motion photos)
-  - Video
-  - All
- Condition
-  - Not in any album
-  - Archived
-  - Favorited
-  - Rating
-
-<Tabs>
-  <TabItem value="Computer" label="Computer" default>
-
-Some search examples:
+| Type                                | Description                                           |
+| ----------------------------------- | ----------------------------------------------------- |
+| People                              | Faces that are recognized in your photos/videos.      |
+| Contextual                          | Content of the photos and videos.                     |
+| File name or extension              | Full or partial file's name, or file's extension      |
+| Description                         | Description added to assets.                          |
+| Optical Character Recognition (OCR) | Text in images                                        |
+| Locations                           | Cities, states, and countries from reverse geocoding. |
+| Tags                                | Tags assigned or extracted from assets.               |
+| Camera                              | make, model and lens model                            |
+| Time frame                          | Start and end date of a specific time bucket          |
+| Media type                          | Image or video or both                                |
+| Display options                     | In Archive, in Favorites or Not in any album          |
+| Start rating                        | User-assigned start rating                            |

 <img src={require('./img/advanced-search-filters.webp').default} width="70%" title='Advanced search filters' />

-<img src={require('./img/search-ex-1.webp').default} width="70%" title='Search Example 1' />
-
-</TabItem>
-  <TabItem value="Mobile" label="Mobile">
-
-<img src={require('./img/mobile-smart-search.webp').default} width="30%" title='Smart search on mobile' />
-
-</TabItem>
-</Tabs>
-
 ## Configuration

 Navigating to `Administration > Settings > Machine Learning Settings > Smart Search` will show the options available.