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

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:

# 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

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:

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:

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

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

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:

Enable by adding the transcoding override file:

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:

Enable with the ML override file:

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:

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

Adjust in Administration → Settings → Image.

3.4 Default Video Transcoding Settings

Adjust in Administration → Settings → Video Transcoding.

3.5 Machine Learning Defaults

Adjust thresholds in Administration → Settings → Machine Learning.

3.6 Default Scheduled Tasks

Immich runs several background jobs on a schedule:

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:

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):

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:

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

npm install -g @immich/cli

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

5.3 Authenticate the CLI

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

Verify the connection:

immich server-info

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

5.4 Upload a Folder with the CLI

Basic upload:

immich upload /path/to/photos

Upload recursively:

immich upload --recursive /path/to/photos

Upload and auto-create albums from folder names:

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

Upload all assets into a single named album:

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

Preview without uploading:

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

Delete local files after successful upload:

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

Delete local duplicates (already on server) without uploading:

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

Watch a folder and auto-upload new files:

immich upload --watch /path/to/photos

Increase upload concurrency for faster transfers:

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

5.5 Full CLI Upload Options Reference

Global CLI options:

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 and select Google Photos.
2. Extract the archive on your machine.
3. Upload with the CLI, using --album to recreate your Google Photos albums:

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:

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:

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:

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:

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, select Google Photos, extract the archive, then upload:

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:

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

Read the release notes 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.