# Immich — User Guide

Immich is a self-hosted photo and video management platform — a privacy-first
alternative to Google Photos. It backs up your mobile photos and videos
automatically, surfaces them through AI-powered search (semantic CLIP search,
facial recognition, OCR), and gives you albums, sharing, maps, memories, and
more. Everything runs on your own hardware; your media never touches a
third-party cloud.

**Version:** 2.7.5 | **License:** AGPL-3.0

> [!IMPORTANT]
> Immich is under active development. Features and interfaces change
> frequently. This guide is pinned to version 2.7.5 (commit `6aadb7b`).
> Always check the [official changelog](https://github.com/immich-app/immich/releases)
> before upgrading.

---

## 1. Quick Start

Get Immich running in under ten minutes with Docker Compose.

### 1.1 Prerequisites

- Docker Engine 24+ and Docker Compose v2
- A host with at least 4 GB RAM (8 GB recommended when machine-learning features are enabled)
- Sufficient storage for your photo library

### 1.2 Five-Step Launch

**Step 1 — Download the official Compose files**

```bash
mkdir ~/immich-app && cd ~/immich-app
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env
```

**Step 2 — Edit `.env`**

Open `.env` and set at minimum:

```dotenv
# Where your photos and videos will be stored on the host
UPLOAD_LOCATION=/your/media/path

# Database credentials — change these before first launch
DB_PASSWORD=change_me_now
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

# Pin to a specific version or use 'release' for latest stable
IMMICH_VERSION=release
```

**Step 3 — Start the stack**

```bash
docker compose up -d
```

**Step 4 — Open the web UI**

Navigate to `http://<your-server-ip>:2283`. The first visit presents a setup
wizard for creating the admin account.

**Step 5 — Install the mobile app**

Download **Immich** from the App Store (iOS) or Google Play (Android), enter
your server URL (`http://<ip>:2283`), log in, and enable background backup.

> [!TIP]
> Put Immich behind a reverse proxy with TLS before exposing it to the
> internet. Never expose port 2283 directly without TLS. See the Admin Guide
> for Nginx, Caddy, and Traefik examples.

---

## 2. Installation

### 2.1 Docker Compose (Recommended)

The canonical install method. The Compose stack runs four services:

| Service | Image | Purpose | Port |
|---|---|---|---|
| `immich-server` | `ghcr.io/immich-app/immich-server` | API + web UI + microservices | 2283 |
| `immich-machine-learning` | `ghcr.io/immich-app/immich-machine-learning` | CLIP, face recognition, OCR | 3003 (internal) |
| `redis` / `valkey` | `valkey:9` | Job queue broker | internal |
| `database` | `ghcr.io/immich-app/postgres:14-vectorchord` | PostgreSQL + vector extensions | internal |

All four services must run together. The server will not start without the
database and Redis.

### 2.2 Rootless Compose (Optional)

A rootless variant stores the database in a user-writable host path instead of
a Docker-managed volume:

```dotenv
DB_DATA_LOCATION=/home/youruser/immich-db
```

Use `hwaccel.transcoding.yml` or `hwaccel.ml.yml` override files to add
hardware acceleration (see Sections 2.5 and 2.6).

### 2.3 Environment Variables Reference

| Variable | Required | Default | Description |
|---|---|---|---|
| `UPLOAD_LOCATION` | Yes | — | Host path for uploaded media |
| `DB_PASSWORD` | Yes | — | PostgreSQL password |
| `DB_USERNAME` | Yes | `postgres` | PostgreSQL username |
| `DB_DATABASE_NAME` | Yes | `immich` | PostgreSQL database name |
| `IMMICH_VERSION` | No | `release` | Version tag to pull |
| `DB_DATA_LOCATION` | No | Docker volume | Database storage path (rootless) |
| `IMMICH_MACHINE_LEARNING_ENABLED` | No | `true` | Set `false` to disable ML service |
| `IMMICH_MACHINE_LEARNING_URL` | No | `http://immich-machine-learning:3003` | ML service URL |

> [!WARNING]
> Never use a weak `DB_PASSWORD`. Although the database port is not exposed
> externally by default, a weak password is a significant risk if your
> network perimeter is breached or the port is later exposed accidentally.

### 2.4 Upgrading

```bash
cd ~/immich-app
docker compose pull
docker compose up -d
```

Immich applies database migrations automatically on startup. Read the release
notes before every upgrade; some versions include breaking changes or require
incremental upgrades.

> [!CAUTION]
> Never skip major versions. If you are several releases behind, upgrade
> one major version at a time and verify the stack is healthy between steps.
> Check `docker compose ps` and `docker compose logs` after each upgrade.

### 2.5 Hardware-Accelerated Transcoding

Immich supports hardware-accelerated video transcoding:

| Accelerator | Backend |
|---|---|
| NVIDIA GPU | NVENC |
| Intel GPU | QuickSync |
| Rockchip SoC | RKMPP |
| AMD / Intel (Linux) | VAAPI |

Enable by adding the transcoding override file:

```bash
docker compose -f docker-compose.yml -f hwaccel.transcoding.yml up -d
```

Then choose the accelerator in **Administration → Settings → Video Transcoding**.

### 2.6 Hardware-Accelerated Machine Learning

ML inference can also be hardware-accelerated:

| Accelerator | Backend |
|---|---|
| NVIDIA GPU | CUDA |
| AMD GPU | ROCm |
| Intel GPU | OpenVINO |
| ARM | ARMNN / RKNN |

Enable with the ML override file:

```bash
docker compose -f docker-compose.yml -f hwaccel.ml.yml up -d
```

Select the backend in **Administration → Settings → Machine Learning**.

### 2.7 Disabling the Machine-Learning Service

If your server lacks the RAM for ML inference, set this in `.env` and restart:

```dotenv
IMMICH_MACHINE_LEARNING_ENABLED=false
```

This disables smart search, facial recognition, and OCR. Standard browsing,
albums, sharing, and all other non-ML features remain fully available.

---

## 3. Configuration

### 3.1 Admin Settings Panel

All runtime configuration lives in **Administration → Settings** in the web UI.
Changes take effect immediately without a restart. The settings panel covers:

- **Image** — thumbnail and preview size, format, and quality
- **Storage Template** — how uploaded files are organized on disk
- **Machine Learning** — model selection, confidence thresholds
- **Map** — tile provider URL, reverse geocoding toggle
- **Trash** — retention period
- **Notifications** — SMTP email server
- **OAuth** — SSO configuration
- **Video Transcoding** — codec, quality, hardware acceleration
- **Logging** — log level

> [!NOTE]
> For deployments that need configuration-as-code (GitOps, automated
> provisioning), Immich supports a `config.json` file mounted at the path
> specified by the `IMMICH_CONFIG_FILE` environment variable. See the Admin
> Guide for the full schema.

### 3.2 Storage Template

By default, Immich stores files using internal UUIDs. The **Storage Template**
feature re-organizes uploaded media into a human-readable folder structure.

**Default template (when enabled):**

```
{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}
```

Example result: `2024/2024-07-15/IMG_1234.jpg`

Available template variables include year (`{{y}}`), month (`{{MM}}`), day
(`{{dd}}`), hour (`{{hh}}`), minute (`{{mm}}`), second (`{{ss}}`), and
filename (`{{filename}}`). Enable and customize in
**Administration → Settings → Storage Template**.

> [!NOTE]
> Storage templates are **disabled by default.** Once enabled and applied,
> existing files are physically moved on disk to match the new template. Plan
> this migration before enabling on a large library; it cannot be automatically
> reversed.

### 3.3 Default Image Settings

| Setting | Default |
|---|---|
| Thumbnail format | WebP |
| Thumbnail size | 250 px |
| Thumbnail quality | 80 |
| Preview format | JPEG |
| Preview size | 1440 px |
| Preview quality | 80 |

Adjust in **Administration → Settings → Image**.

### 3.4 Default Video Transcoding Settings

| Setting | Default |
|---|---|
| Video codec | H.264 |
| Audio codec | AAC |
| Encoding preset | ultrafast |
| CRF (quality) | 23 |
| Target resolution | 720p |

Adjust in **Administration → Settings → Video Transcoding**.

### 3.5 Machine Learning Defaults

| Setting | Default |
|---|---|
| CLIP model | ViT-B-32__openai |
| Face recognition model | buffalo_l |
| Face min confidence score | 0.7 |
| Face max cluster distance | 0.5 |
| Min faces to show person | 3 |
| OCR model | PP-OCRv5_mobile |

Adjust thresholds in **Administration → Settings → Machine Learning**.

### 3.6 Default Scheduled Tasks

Immich runs several background jobs on a schedule:

| Task | Schedule |
|---|---|
| Database backup | Daily at 2:00 AM |
| Library scan | Daily at midnight |
| Database cleanup | Nightly at 00:00 |
| Generate memories | Nightly at 00:00 |
| Missing thumbnails | Nightly at 00:00 |
| Cluster faces | Nightly at 00:00 |
| Sync storage quota | Nightly at 00:00 |

Trigger any job manually from **Administration → Jobs** without waiting for the
next scheduled run.

### 3.7 Trash Configuration

The trash holds deleted assets for 30 days by default before permanently
removing them. Configure the retention period in
**Administration → Settings → Trash → Retention Days**. Set to `0` to bypass
trash entirely (permanent delete on first action).

---

## 4. Core Usage

### 4.1 The Web Interface

Access the web UI at `http://<server>:2283`. Main navigation sections:

| Section | Purpose |
|---|---|
| **Photos** (Timeline) | Chronological view of all your media |
| **Explore** | AI-organized views: Places (map) and People (faces) |
| **Albums** | Your curated collections |
| **Sharing** | Shared albums and partner libraries |
| **Archive** | Archived assets (hidden from timeline) |
| **Favorites** | Assets you have starred |
| **Trash** | Deleted assets pending permanent removal |

### 4.2 Timeline

The timeline is your primary library view. Media is grouped by date in reverse
chronological order. The scrubber on the right lets you jump by month or year.

**Selecting assets:** click the circular selector on hover (desktop) or tap
on mobile. Use Shift+click for range selection in bulk operations.

### 4.3 Mobile App Backup

After installing the mobile app:

1. Open Immich → tap your profile icon → **Settings**.
2. Under **Backup**, enable **Background Backup**.
3. Choose which device albums to back up (default: Camera Roll / Camera).
4. Enable **WiFi Only** to restrict uploads to Wi-Fi networks.

The app hashes each file before upload to detect duplicates. The first backup
of a large library can take hours; subsequent backups are incremental.

> [!TIP]
> On Android, if the app stops backing up in the background, grant it
> "Unrestricted" battery optimization access. Go to **Settings → Apps →
> Immich → Battery → Unrestricted**. Many Android OEM skins aggressively
> kill background processes.

### 4.4 Search

Immich provides three complementary search modes from the search bar:

#### Smart Search (Semantic)

Type natural-language descriptions of what you are looking for:

- `sunset at the beach`
- `birthday cake with candles`
- `red car on a highway`

Smart Search uses CLIP embeddings — it understands image content without
relying on metadata. Requires the ML service to be running and assets to be
indexed.

#### Metadata Search

Filter by structured fields using the filter panel (funnel icon):

| Filter | Description |
|---|---|
| Date range | Captured between two dates |
| Camera make / model | EXIF camera data |
| City / state / country | Reverse-geocoded location |
| File type | Photo, video, or both |
| Favorite / archived | Asset status |
| Person | Filter by a recognized face name |

#### Text in Photos (OCR)

Immich indexes text found inside images using OCR. Searching for a license
plate, a sign, or a document title surfaces matching photos. OCR uses the
`PP-OCRv5_mobile` model by default and runs as a background indexing job.

### 4.5 People and Faces

Immich automatically clusters detected faces into **People** groups. Once
clustered, you assign names.

**To name a person:**
1. Go to **Explore → People**.
2. Click an unnamed cluster.
3. Click the **pencil** icon and enter a name.

**To merge incorrectly split clusters:**
1. Open a person's page.
2. Click **...** → **Merge** and select the duplicate cluster to absorb.

**Facial recognition defaults:**

| Setting | Default |
|---|---|
| Model | buffalo_l |
| Min confidence score | 0.7 |
| Max cluster distance | 0.5 |
| Min faces to appear in Explore | 3 |

A person only appears in **Explore → People** once at least 3 faces in your
library meet the confidence threshold.

### 4.6 Albums

Albums are curated collections of assets. Any asset can belong to multiple
albums simultaneously.

**Create an album:**
1. Click **Albums → + New Album**.
2. Enter a name and optional description.
3. Add assets by selecting them in the timeline → **Add to Album**.

**Share an album with a user:** open the album → **Share** → search for a
registered user on your server.

**Share an album publicly:** open the album → **Share Link** → create a shared
link (configurable expiration, password, and download permission).

### 4.7 Shared Links

Shared links let you share individual assets or entire albums with anyone —
no Immich account required for the recipient.

**Create a shared link:**
1. Select an asset or open an album.
2. Click **Share → Create Link**.
3. Configure: expiration date, password, allow-download toggle.
4. Copy the link.

Manage all your shared links from **Sharing → Shared Links**.

### 4.8 Partners

Partners let two Immich users on the same server see each other's libraries.

**Add a partner:**
1. Go to profile icon → **Account Settings → Sharing**.
2. Under **Partners**, click **Add Partner** and search for a user.

Their assets appear in your timeline alongside yours (distinguished by their
avatar). Partnership is directional — each side controls whether they share
with the other.

> [!NOTE]
> Partner sharing is server-local. It only works between accounts on the
> same Immich instance, not between different servers.

### 4.9 Tags

Tags are hierarchical, user-defined labels:

- Use `/` for hierarchy: `travel/europe/italy`
- A parent tag (`travel`) automatically surfaces all child-tagged assets
- Create and apply tags from the asset detail panel or **Administration → Tags**

### 4.10 Stacks

Stacks group related versions of the same scene (burst shots, HDR brackets,
RAW+JPEG pairs) into a single timeline entry.

**Create a stack:**
1. Select the assets to stack (2 or more).
2. Right-click → **Stack**.
3. The first selected asset becomes the primary (cover).

Only the primary shows in the timeline. Click the stack icon to expand all
versions. To unstack: open the stack → click primary → **Unstack**.

### 4.11 Memories

Memories are auto-generated "on this day" collections. Each morning, Immich
surfaces assets captured on this calendar date in prior years.

- View memories at the top of the **Photos** timeline or on the mobile home
  screen.
- Like or dismiss individual memories.
- Generated by the nightly background job.

### 4.12 Map

**Explore → Places** shows a world map of your geotagged assets. Click any
cluster to zoom in; click a pin to open the asset.

Reverse geocoding labels assets with city, state, and country based on GPS
coordinates. Map tiles default to `tiles.immich.cloud`. A custom tile URL can
be set in **Administration → Settings → Map**.

### 4.13 Favorites and Archive

**Favorite:** click the heart icon on any asset. View all favorites under
**Favorites** in the sidebar.

**Archive:** removes an asset from the main timeline without deleting it.
Useful for keeping screenshots and receipts out of your photo feed. Access
archived assets under **Archive** in the sidebar. Archived assets are still
searchable and can be added to albums.

### 4.14 Trash

Deleted assets are held in **Trash** for 30 days (configurable) before
permanent deletion.

- **Restore:** open Trash → select assets → **Restore Selected**.
- **Empty trash:** open Trash → **Empty Trash** to permanently delete all
  trashed assets immediately.
- **Bypass trash:** hold Shift+Delete or select **Permanently Delete** from
  the asset menu to skip the trash entirely.

### 4.15 Activities — Likes and Comments

On shared albums, collaborators can leave likes and comments on individual
assets.

1. Open a shared album → click an asset → click the **speech bubble** icon.
2. Comments are visible to all users with access to the album.
3. Album owners can delete any comment; users can delete their own.

### 4.16 Duplicate Detection

Immich uses visual embeddings (not file hashes) to detect near-duplicate
assets — including re-saved or re-exported copies with different hashes.

Review duplicates from **Administration → Jobs → Duplicate Detection**. Keep
one copy and trash the others.

---

## 5. Common Tasks

### 5.1 Upload from the Web UI

1. Click the **Upload** button (cloud icon, top-right corner).
2. Drag and drop files or click to browse.
3. Immich deduplicates by hash — re-uploading the same file creates no
   duplicate.

### 5.2 Install the CLI

```bash
npm install -g @immich/cli
```

The CLI works on Windows, macOS, and Linux (requires Node.js).

### 5.3 Authenticate the CLI

```bash
immich login http://<server>:2283 <your-api-key>
```

Verify the connection:

```bash
immich server-info
```

Credentials are stored in `~/.config/immich/` by default.

### 5.4 Upload a Folder with the CLI

**Basic upload:**

```bash
immich upload /path/to/photos
```

**Upload recursively:**

```bash
immich upload --recursive /path/to/photos
```

**Upload and auto-create albums from folder names:**

```bash
immich upload --recursive --album /path/to/photos
```

**Upload all assets into a single named album:**

```bash
immich upload --album-name "Summer 2024" /path/to/photos
```

**Preview without uploading:**

```bash
immich upload --dry-run --recursive /path/to/photos
```

**Delete local files after successful upload:**

```bash
immich upload --recursive --delete /path/to/photos
```

**Delete local duplicates (already on server) without uploading:**

```bash
immich upload --recursive --delete-duplicates /path/to/photos
```

**Watch a folder and auto-upload new files:**

```bash
immich upload --watch /path/to/photos
```

**Increase upload concurrency for faster transfers:**

```bash
immich upload --recursive --concurrency 8 /path/to/photos
```

### 5.5 Full CLI Upload Options Reference

| Flag | Env Var | Default | Description |
|---|---|---|---|
| `-r, --recursive` | `IMMICH_RECURSIVE` | `false` | Recurse into subdirectories |
| `-i, --ignore <pattern>` | `IMMICH_IGNORE_PATHS` | — | Glob pattern to exclude |
| `-h, --skip-hash` | `IMMICH_SKIP_HASH` | `false` | Skip hashing (faster, no dedup) |
| `-H, --include-hidden` | `IMMICH_INCLUDE_HIDDEN` | `false` | Include hidden folders |
| `-a, --album` | `IMMICH_AUTO_CREATE_ALBUM` | `false` | Auto-create albums from folder names |
| `-A, --album-name <name>` | `IMMICH_ALBUM_NAME` | — | Add all assets to this album (conflicts with `--album`) |
| `-n, --dry-run` | `IMMICH_DRY_RUN` | `false` | Preview only (conflicts with `--skip-hash`) |
| `-c, --concurrency <n>` | `IMMICH_UPLOAD_CONCURRENCY` | CPU count − 1 | Parallel upload threads |
| `-j, --json-output` | `IMMICH_JSON_OUTPUT` | `false` | Machine-readable JSON output |
| `--delete` | `IMMICH_DELETE_ASSETS` | — | Delete local files after successful upload |
| `--delete-duplicates` | `IMMICH_DELETE_DUPLICATES` | — | Delete local files already present on server |
| `--no-progress` | `IMMICH_PROGRESS_BAR` | — | Hide progress bars |
| `--watch` | `IMMICH_WATCH_CHANGES` | `false` | Watch folder, upload on change |

**Global CLI options:**

| Flag | Env Var | Default | Description |
|---|---|---|---|
| `-d, --config-directory <dir>` | `IMMICH_CONFIG_DIR` | `~/.config/immich/` | Config directory |
| `-u, --url [url]` | `IMMICH_INSTANCE_URL` | stored login | Server URL |
| `-k, --key [key]` | `IMMICH_API_KEY` | stored login | API key |

> [!TIP]
> All CLI flags can be set via environment variables, making it easy to
> configure uploads in shell scripts and CI pipelines without exposing
> credentials on the command line.

### 5.6 Generate an API Key

1. Click your profile icon → **Account Settings → API Keys**.
2. Click **New API Key**, give it a descriptive name, and copy the key.

> [!WARNING]
> API keys are shown only once at creation. Store the key in a password
> manager immediately. If lost, delete the key and create a new one.

### 5.7 Create and Share an Album

1. Click **Albums → + New Album** in the left sidebar.
2. Enter a name and optional description.
3. Select assets in the timeline → right-click → **Add to Album** → choose
   your album.
4. To share: open the album → **person+ icon** → enter a username, or choose
   **Share Link** for a public link.

### 5.8 Share a Single Photo or Video

1. Click the asset to open it.
2. Click the **share** (chain link) icon.
3. Choose **Create Link**, configure options, and copy the URL.

### 5.9 Download Assets

**Single asset:** open it → click the **download** icon.

**Multiple assets:** select them in the timeline → **Download** (packages as
a ZIP archive).

**Entire album:** open the album → **...** menu → **Download**.

### 5.10 Create a Password-Protected Shared Link

1. Select assets or open an album.
2. Click **Share → Create Link**.
3. Enable **Password Protection** and enter a password.
4. Optionally set an expiration date.
5. Copy and distribute the link. Recipients must enter the password to view.

### 5.11 Name a Person

1. Go to **Explore → People**.
2. Click an unnamed cluster.
3. Click the **pencil** icon and type the person's name → Enter.

### 5.12 Merge Duplicate Face Clusters

1. Open the target person's page.
2. Click **...** → **Merge**.
3. Select the other cluster(s) to merge into this one.
4. Confirm.

### 5.13 Hide a Person from Explore

If Immich clusters a pet, object, or someone you do not want tracked:

1. Open the person's page.
2. Click **...** → **Hide**.

The cluster is removed from **Explore → People**. The underlying face
detections are retained; you can re-show the person later if needed.

### 5.14 Archive Assets

Select one or more assets → right-click → **Archive**. Archived assets
disappear from the main timeline but remain searchable. Unarchive from the
**Archive** section in the sidebar.

### 5.15 Add to Favorites

Click the **heart** icon on any asset (in detail view or on hover in the
timeline). View all favorites under **Favorites** in the sidebar.

### 5.16 Stack Burst Shots or RAW+JPEG Pairs

1. Select the assets to stack.
2. Right-click → **Stack**.
3. The first selected asset becomes the cover.

To unstack: open the stack → select the primary → **Unstack**.

### 5.17 Apply Tags

1. Open an asset.
2. In the right-hand detail panel, click **Add Tag**.
3. Type an existing tag name or create a new one. Use `/` for hierarchy:
   `trip/italy/rome`.
4. Press Enter.

### 5.18 Search with Combined Filters

1. Click the **search bar** at the top.
2. Click the **filter** (funnel) icon.
3. Combine: date range, location, camera model, file type, person, favorites.
4. Press **Search**.

### 5.19 Find Photos by Location

Go to **Explore → Places**. Click map clusters to zoom in. Click a pin to
open the asset. Use pinch-to-zoom on mobile.

### 5.20 View and Edit Asset Metadata

Open an asset → click the **info (i)** icon:

- **Capture date/time** — editable (useful for scanned photos)
- **Camera make and model** — from EXIF
- **GPS coordinates** — view or set manually
- **Description** — editable free-text
- **File size, dimensions, format** — read-only

### 5.21 Edit Capture Date

If an asset has a wrong date (common for scanned photos):

1. Open the asset → click the **info** icon.
2. Click the date/time field → **Edit**.
3. Enter the correct date and time → **Save**.

The corrected date repositions the asset in the timeline.

### 5.22 Delete Assets

**Soft delete (trash):** select assets → **Delete** (or press Delete key).
Assets go to Trash for 30 days before permanent removal.

**Permanent delete:** select assets → Shift+Delete, or choose
**Permanently Delete** from the context menu.

### 5.23 Restore from Trash

1. Open **Trash** from the sidebar.
2. Select the assets to restore.
3. Click **Restore Selected**.

Or restore all: **Restore All**.

### 5.24 Import an External Library (Existing NAS Collection)

Index files stored outside the upload directory without moving them:

1. Go to **Administration → External Libraries → Create Library**.
2. Set the import paths (directories bind-mounted into the server container).
3. Trigger a scan or wait for the nightly automatic scan.

> [!NOTE]
> External library files are read-only from Immich's perspective. Immich
> will not move or delete them. If a file is removed from the filesystem,
> it is marked offline in Immich.

### 5.25 Use Sidecar Files (RAW + XMP)

Place an `.xmp` sidecar next to the original file with the same base name:

```
photo.ARW
photo.ARW.xmp
```

Immich reads the sidecar during import. To re-scan sidecars for existing
assets: **Administration → Jobs → Sidecar**.

### 5.26 Add a Partner

1. Profile icon → **Account Settings → Sharing → Partners**.
2. Click **Add Partner** and search for a user on your server.
3. Once added, their assets appear in your timeline.

### 5.27 Use OAuth / SSO Login

If your admin has configured OAuth, a **Login with OAuth** button appears on
the sign-in page. Click it to authenticate via your identity provider. If
account linking fails, see Section 6 Troubleshooting.

### 5.28 Change Your Password

Profile icon → **Account Settings → Security → Change Password**.

### 5.29 Enable Two-Factor Authentication

Profile icon → **Account Settings → Security → Two-Factor Authentication →
Enable**. Scan the QR code with an authenticator app and save your backup
codes in a safe place.

### 5.30 Configure Email Notifications

Profile icon → **Account Settings → Notifications**. Toggle alerts for share
invitations and album activity (requires SMTP configured by your admin).

### 5.31 Import Google Photos Library

1. Download your data via [Google Takeout](https://takeout.google.com) and
   select Google Photos.
2. Extract the archive on your machine.
3. Upload with the CLI, using `--album` to recreate your Google Photos albums:

```bash
immich upload --recursive --album /path/to/Takeout/Google\ Photos
```

### 5.32 Upload from CI / Automation

Use environment variables to avoid passing secrets on the command line:

```bash
export IMMICH_INSTANCE_URL=http://your-server:2283
export IMMICH_API_KEY=your_api_key

immich upload --recursive --json-output /path/to/photos
```

The `--json-output` flag emits machine-readable JSON for each file, suitable
for parsing in scripts.

---

## 6. Troubleshooting

### Error: "Assets cannot be added to the album"

**Cause:** A known issue (GitHub #27545) when adding partner-shared photos to
a personal album via the web client. Cross-user asset ownership restrictions
prevent the operation.

**Solution:** Ask the partner to add the asset to a shared album they own.
Check the GitHub issue for the latest fix status.

**Prevention:** Wait for the upstream fix before relying on this workflow.

---

### Error: ML container stays "unhealthy" after update

**Cause:** The machine-learning container failed to initialize, often due to
a model file mismatch or interrupted model download during an upgrade
(GitHub #27228).

**Solution:**

```bash
docker compose down
docker volume rm immich_model-cache
docker compose up -d
docker compose logs -f immich-machine-learning
```

Wait for the models to re-download completely before evaluating health.

**Prevention:** Ensure sufficient disk space before upgrading. Do not
interrupt the container during its first startup after an upgrade.

---

### Error: OAuth login fails / account linking error

**Cause:** The email returned by your OAuth provider does not exactly match the
email on your Immich account — typically a case mismatch (GitHub #26839).
Example: `[email removed]` vs `[email removed]`.

**Solution:**

1. Log in with your password instead of OAuth.
2. Go to **Account Settings → Profile** and update your email to match exactly
   what your OAuth provider sends (usually lowercase).
3. Try OAuth login again.

**Prevention:** Use lowercase email addresses consistently in both your
identity provider and Immich.

---

### Error: Faces disappeared from Explore → People

**Cause:** A background job (face clustering or model reindex) may have cleared
the face database without reprocessing, or a model change reset all assignments
(GitHub #27637).

**Solution:**

1. Go to **Administration → Jobs**.
2. Run **Facial Recognition → Queue All** to reprocess the entire library.
3. Allow the job to complete (may take several hours for large libraries).

**Prevention:** After any upgrade that changes ML models, let the nightly
face-clustering job complete before evaluating results.

---

### Error: New photos not appearing in the timeline

**Cause:** Upload completed, but thumbnail generation or search indexing has not
finished, or the browser cache is stale (GitHub #27787).

**Solution:**

1. Wait a few minutes and hard-refresh the page (Ctrl+Shift+R / Cmd+Shift+R).
2. If assets still do not appear: **Administration → Jobs → Generate Thumbnails
   → Queue Missing**.
3. Check for errors: `docker compose logs immich-server`.

**Prevention:** Ensure sufficient CPU and disk I/O for thumbnail generation.
Large video files can take several minutes each.

---

### Error: Android app stuck on "Hashing" / won't sync

**Cause:** The Android backup process hashes files before upload to detect
duplicates. On large libraries or slow storage, this looks stuck. Battery
optimization may kill the background process (GitHub #27846).

**Solution:**

1. **Android Settings → Apps → Immich → Battery → Unrestricted**.
2. In the Immich app: **Settings → Backup → Background Backup** — toggle off
   then on.
3. For the initial backup of a very large library, keep the app in the
   foreground.

**Prevention:** Grant battery exemptions before starting the initial backup.

---

### Error: Restore on another machine not working

**Cause:** The database dump or volume restore was incomplete, the new machine
uses a different user ID causing file permission issues, or `UPLOAD_LOCATION`
points to the wrong path (GitHub #27684).

**Solution:**

1. Verify the database backup file is intact (check file size against the
   original).
2. Ensure `UPLOAD_LOCATION` points to the restored media directory.
3. Fix permissions: `chown -R 1000:1000 /your/upload/location`
4. Start the stack and check logs: `docker compose up -d && docker compose logs`.

**Prevention:** Test restores periodically. Document your `UPLOAD_LOCATION`
and volume mappings. See the Admin Guide for the full backup/restore procedure.

---

### Error: "Invalid API key" with the CLI

**Cause:** The key is incorrect, was deleted, or you are pointing at the wrong
server URL.

**Solution:**

```bash
immich logout
immich login http://<server>:2283 <new-api-key>
immich server-info
```

**Prevention:** Use `IMMICH_API_KEY` as an environment variable in scripts to
make rotation painless.

---

### Error: Videos won't play / "Transcoding failed"

**Cause:** The video codec or container is unsupported by the browser, and the
server-side transcoding job failed.

**Solution:**

1. Check logs: `docker compose logs immich-server | grep -i transcode`
2. Trigger re-transcoding: open the asset → **...** → **Reprocess Asset**.
3. If hardware transcoding is enabled, verify device access:
   `docker compose logs immich-server | grep -i hwaccel`

**Prevention:** Confirm hardware transcoding works with a test video before
relying on it for the whole library. Software transcoding (H.264) is the most
compatible baseline.

---

### Error: Thumbnails show as grey boxes

**Cause:** Thumbnail generation failed, often due to disk space exhaustion or
a processing error for that specific file type.

**Solution:**

1. Check disk space: `df -h /your/upload/location`
2. **Administration → Jobs → Generate Thumbnails → Queue Missing**.
3. Monitor job progress in the Jobs panel.

**Prevention:** Alert when `UPLOAD_LOCATION` storage exceeds 80% capacity.

---

### Error: Smart search returns irrelevant results

**Cause:** CLIP embeddings are out of date, or newly uploaded assets have not
been indexed yet.

**Solution:**

1. **Administration → Jobs → Smart Search → Queue Missing** for new assets.
2. **Queue All** to rebuild the entire index (expensive on large libraries).

**Prevention:** Allow indexing jobs to complete after any bulk import before
evaluating search quality.

---

### Error: Map shows no pins / "Map data unavailable"

**Cause:** Reverse geocoding failed, or the map tile server (`tiles.immich.cloud`)
is unreachable from the server.

**Solution:**

1. Verify outbound internet access from the server host.
2. Re-run geocoding: **Administration → Jobs → Reverse Geocoding → Queue All**.
3. If using a custom tile server, verify the URL in
   **Administration → Settings → Map**.

**Prevention:** Ensure reliable outbound internet from the server for geocoding
and tile services.

---

### Error: "Quota exceeded" when uploading

**Cause:** Your storage quota set by the admin has been reached.

**Solution:** Delete assets you no longer need, or contact your Immich
administrator to increase your quota.

---

### Error: Shared link returns "not found" or is expired

**Cause:** The link passed its expiration date, was deleted by the creator, or
the server URL changed.

**Solution:** Ask the link creator to generate a new shared link with an
updated expiration.

---

### Error: OCR search not finding text in photos

**Cause:** OCR has not yet been indexed for those assets, or the text is too
small, blurry, or low-contrast for the model.

**Solution:**

1. **Administration → Jobs → OCR → Queue Missing** to process unindexed assets.
2. Very small or degraded text may not be detectable at the default model
   resolution. No workaround exists for the current model.

**Prevention:** Allow the nightly indexing job to run after bulk imports.

---

### Error: Duplicate assets appearing after CLI upload

**Cause:** `--skip-hash` was used, bypassing deduplication. Or the same files
were imported via two paths (direct upload and external library).

**Solution:**

1. **Administration → Jobs → Duplicate Detection → Queue All**.
2. Review and resolve detected duplicates.

**Prevention:** Avoid `--skip-hash` unless you are certain no duplicates exist.

---

### Error: "Cannot connect to server" on the mobile app

**Cause:** Incorrect server URL, server is down, or a firewall blocks port 2283.

**Solution:**

1. Verify the stack is running: `docker compose ps`
2. Test connectivity: `curl http://<server>:2283/api/server/ping`
3. Check host firewall rules for port 2283.
4. Verify DNS resolution if using a hostname.

**Prevention:** Use a stable local IP or hostname. Use a reverse proxy with
TLS for remote access.

---

### Error: Background backup stops after iOS update

**Cause:** iOS may revoke background app permissions after an OS update.

**Solution:**

1. **iOS Settings → Immich → Background App Refresh → On**.
2. In the Immich app: **Settings → Backup → Background Backup** — toggle off
   then on.

**Prevention:** After every iOS update, confirm Background App Refresh is
still enabled for Immich.

---

### Error: External library scan finds no new files

**Cause:** The external path is not bind-mounted into the `immich-server`
container, so the container cannot see the filesystem.

**Solution:**

1. Edit `docker-compose.yml` to add the path as a volume mount on
   `immich-server`.
2. Restart: `docker compose up -d`
3. Trigger a manual scan: **Administration → External Libraries → Scan**.

**Prevention:** After any Compose file change, verify mounts with
`docker compose exec immich-server ls /path/to/library`.

---

### Error: "Database migration failed" on startup

**Cause:** A migration script encountered an error — often disk full, or a
schema conflict from skipping versions.

**Solution:**

1. `docker compose logs immich-server | grep -i migration`
2. Free disk space if needed.
3. If you skipped versions, restore the last working backup and upgrade
   incrementally.

**Prevention:** Never skip major versions. Read release notes before upgrading.

---

### Error: High memory usage from the ML container

**Cause:** ML models are loaded into RAM and stay resident. The default CLIP and
face recognition models together use 1–2 GB of RAM.

**Solution:**

1. Disable unused ML features: **Administration → Settings → Machine Learning**.
2. Or disable the entire ML service: set `IMMICH_MACHINE_LEARNING_ENABLED=false`
   in `.env` and restart.

**Prevention:** Allocate at least 4 GB RAM to the host; 8 GB for comfortable
ML operation with all features enabled.

---

### Error: SMTP email notifications not sending

**Cause:** Incorrect SMTP credentials, wrong port/TLS setting, or the mail
server is blocking the connection.

**Solution:**

1. **Administration → Settings → Notifications → Email → Test**.
2. Review the test result for the specific SMTP error message.
3. Verify host, port, TLS/STARTTLS setting, and credentials.

**Prevention:** Test SMTP after initial configuration and after any credential
rotation.

---

## 7. FAQ

**Q: Is Immich a replacement for Google Photos?**
Immich covers the core use cases: automatic mobile backup, browsable timeline, albums, AI-powered search, face recognition, sharing, and map. It does not replicate every Google Photos editing tool, but for most users it is a fully capable self-hosted alternative.

**Q: What file types does Immich support?**
Common image formats (JPEG, PNG, WebP, HEIC, HEIF, TIFF, GIF), RAW formats from major camera manufacturers, and video containers including MP4, MOV, MKV, and AVI. RAW support depends on the processing libraries included in the server container.

**Q: Does Immich store my originals unmodified?**
Yes. Original files are stored unmodified in `UPLOAD_LOCATION`. Thumbnails and previews are generated separately and do not alter the originals. The storage template feature only changes folder organization, never file content.

**Q: Can multiple users share one Immich instance?**
Yes. Immich is fully multi-user. The admin can create additional accounts from **Administration → Users**. Each user has a private library. Users can share albums, create shared links, and set up partner access.

**Q: Does Immich work without internet access?**
Yes, for core functionality. Uploading, browsing, searching, and sharing all work on a closed LAN. Map tiles and reverse geocoding require outbound internet access (or a self-hosted tile server). Initial ML model downloads also require internet.

**Q: How does deduplication work?**
The CLI hashes each file (SHA-1) before upload and skips files whose hash already exists on the server. The web UI also deduplicates by hash on upload. The separate visual duplicate detection feature uses CLIP embeddings to find visually similar assets regardless of file hash — catching re-saved or re-exported copies.

**Q: Where are my files stored on the server?**
In the directory you set as `UPLOAD_LOCATION` in `.env`. This path is bind-mounted into the `immich-server` container at `/data`.

**Q: What happens if I lose the database?**
The original media files remain safe in `UPLOAD_LOCATION`, but without the database, Immich cannot map assets to metadata, albums, tags, or users. You would need to re-import and re-organize everything. Always back up your database. The default automated backup runs daily at 2 AM, retaining 14 copies.

**Q: Can I use Immich with my existing NAS photo collection?**
Yes, via External Libraries. Point Immich at your NAS paths (bind-mounted into the container) and it indexes without moving your files. External library files are read-only from Immich's perspective.

**Q: Does Immich edit photos?**
Immich does not have a built-in photo editor. You can view, organize, tag, and share, but editing must be done in external tools. Originals are always preserved.

**Q: Can I access Immich from outside my home network?**
Yes, with a reverse proxy (Nginx, Caddy, or Traefik) handling TLS termination. Never expose port 2283 directly to the internet without TLS. See the Admin Guide for reverse proxy configuration.

**Q: How do I reset the admin password?**
Connect to the running container:

```bash
docker exec -it immich-server immich-admin reset-admin-password
```

See the Admin Guide for the full procedure.

**Q: Does Immich support RAW + JPEG pairs?**
Yes. Immich detects RAW+JPEG pairs and stacks them automatically. The JPEG is shown as the primary; the RAW is the stacked version.

**Q: How long does the initial mobile backup take?**
It depends on library size, network speed, and server hardware. A 10,000-photo library over a LAN typically takes 1–3 hours for upload, plus additional time for thumbnail generation and ML indexing. Keep the app in the foreground for the initial run on Android.

**Q: Can I run Immich on a Raspberry Pi?**
The server and database images are available for ARM64 (Raspberry Pi 4/5 with a 64-bit OS). The ML container is also ARM64-compatible. ML performance will be slower. Do not enable NVIDIA/AMD hardware acceleration options on ARM.

**Q: What happens when trash retention expires?**
Assets in Trash older than the retention period (default 30 days) are permanently deleted by the nightly cleanup job. This cannot be undone.

**Q: Can I change the trash retention period?**
Yes. **Administration → Settings → Trash → Retention Days**. Set to `0` to disable trash (permanent delete on first action).

**Q: How does facial recognition work?**
The ML container detects faces in each photo using the `buffalo_l` model. Detected faces are grouped into clusters using vector distance comparisons. You name the clusters; Immich labels all matching faces with that name. Clustering runs as a nightly background job.

**Q: Why are some people not showing up in Explore → People?**
A person only appears after at least 3 faces in your library meet the minimum confidence score (default 0.7). Photos with 1–2 matches, or faces below the threshold, won't generate a visible cluster.

**Q: Can I import my Google Photos library?**
Yes. Download via [Google Takeout](https://takeout.google.com), select Google Photos, extract the archive, then upload:

```bash
immich upload --recursive --album /path/to/Takeout/Google\ Photos
```

The `--album` flag recreates your Google Photos albums from folder names.

**Q: Does the CLI work on Windows?**
Yes. Install via `npm install -g @immich/cli`. The CLI is a Node.js package and runs on Windows, macOS, and Linux.

**Q: How do I back up Immich?**
Back up two things: (1) the database — Immich creates a PostgreSQL dump daily at 2 AM, kept for 14 days in the database volume; (2) the media files — back up `UPLOAD_LOCATION` with rsync, Restic, Duplicati, or your preferred tool. See the Admin Guide for the full backup strategy and restore procedure.

**Q: Can I use Immich with a custom domain and HTTPS?**
Yes. Set up a reverse proxy to terminate TLS and forward to `localhost:2283`. Caddy with automatic HTTPS is the simplest option. See the Admin Guide for Nginx, Caddy, and Traefik examples.

**Q: What ports does Immich use?**
Port `2283` is the only port you need to expose — it serves both the web UI and the API. Internal services (ML on `3003`, PostgreSQL, Redis) communicate within the Docker network and are not exposed by default.

**Q: Does Immich support video?**
Yes. Immich stores, displays, and transcodes videos. Default transcoding uses H.264 video (CRF 23, ultrafast preset) and AAC audio at 720p. Hardware-accelerated transcoding is supported for NVIDIA, Intel, AMD, and Rockchip hardware.

**Q: Can I share albums with people who don't have an Immich account?**
Yes. Create a Shared Link for the album. Recipients get a URL they open in any browser — no account needed. You can password-protect the link and set an expiration date.

**Q: What is the difference between a shared album and a partner?**
A shared album is a specific curated collection shared with named users. A partner relationship shares your entire library (past and future) with another user on the same server. Partners see your full timeline, not just selected albums.

**Q: How do I update Immich?**
Pull new images and restart the stack:

```bash
cd ~/immich-app
docker compose pull
docker compose up -d
```

Read the [release notes](https://github.com/immich-app/immich/releases) before upgrading. Never skip major versions.

**Q: Is there a desktop app?**
There is no official desktop app. The web UI at `http://<server>:2283` is the primary desktop interface. The CLI (`@immich/cli`) handles bulk uploads and automation from the command line.

**Q: What is Workflows in Immich?**
Workflows are trigger-based automations with plugin support, allowing you to define actions that fire when certain events occur (e.g., a new asset is uploaded). This feature is under active development; see the Admin Guide for current capabilities.

**Q: What are External Libraries vs. uploaded assets?**
Uploaded assets are copied into Immich's `UPLOAD_LOCATION` and fully managed by Immich (including trash, move, delete). External library assets remain in their original location on the filesystem and are indexed read-only — Immich will not move or delete them.

---

_Generated May 2026 from immich-app/immich at 6aadb7b. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._