Immich — Administrator & Developer Guide

Immich is a self-hosted photo and video management platform — a privacy-first alternative to Google Photos. This guide covers every aspect of running, operating, and extending Immich: architecture internals, configuration reference, deployment patterns, security hardening, and developer integration. Version covered: 2.7.5 (AGPL-3.0).

Note

This is the Admin & Developer Guide. For end-user workflows — uploading, sharing, albums, mobile backup — see the Immich User Guide.

1. Architecture Overview

1.1 High-Level Topology

Immich is a monorepo product composed of six runtime components:

┌────────────────────────────────────────────────────────┐
│  Clients: Web (SvelteKit), Mobile (Flutter), CLI       │
└────────────────┬───────────────────────────────────────┘
                 │ HTTP/WebSocket (port 2283)
┌────────────────▼───────────────────────────────────────┐
│  immich-server  (NestJS / Node.js 24+)                 │
│  ├─ API Worker        (HTTP + WebSocket)               │
│  ├─ Microservices Worker  (BullMQ consumers)           │
│  └─ Maintenance Worker    (backup + schema ops)        │
└──────┬──────────────┬─────────────────────────────────┘
       │              │
┌──────▼──────┐  ┌────▼────────────────────────────────┐
│  PostgreSQL  │  │  Redis / Valkey  (BullMQ broker)    │
│  (port 5432) │  │  (port 6379)                        │
└─────────────┘  └─────────────────────────────────────┘
       │
┌──────▼──────────────────────────────────────────────┐
│  immich-machine-learning  (Python / FastAPI)         │
│  Gunicorn + Uvicorn, port 3003                      │
│  ONNX Runtime — CLIP · FaceNet · OCR                │
└─────────────────────────────────────────────────────┘

All persistent state lives in PostgreSQL and the media filesystem. Redis is ephemeral — losing it causes no data loss, only in-flight job loss.

1.2 immich-server — NestJS Runtime

The server binary runs as three distinct worker types (controlled by environment variables):

A single container runs all three workers by default. Separate them at scale using IMMICH_WORKERS_INCLUDE / IMMICH_WORKERS_EXCLUDE.

Key server characteristics:

• Framework: NestJS with full DI, Guards, Interceptors, and BullMQ integration
• Static asset serving: sirv for the compiled SvelteKit bundle
• Request timeout: 24 hours (accommodates very large video uploads)
• Security headers: Helmet middleware (configurable via IMMICH_HELMET_FILE)
• Validation: ZodValidationPipe + ZodSerializerInterceptor
• OpenAPI spec: auto-generated from decorators

1.3 NestJS Module Architecture

ApiModule (HTTP, port 2283)
├── 64 controllers: activity, album, api-key, asset, auth,
│   download, face, job, library, map, memory, notification,
│   partner, person, plugin, queue, search, server,
│   session, shared-link, stack, sync, system-config,
│   system-metadata, tag, timeline, trash, user, version,
│   view, workflow …
├── 48 services (all extending BaseService)
├── 58 repository files (Kysely-backed)
├── Middleware: AuthGuard, ErrorInterceptor,
│   FileUploadInterceptor, LoggingInterceptor,
│   GlobalExceptionFilter
└── ZodValidationPipe, ZodSerializerInterceptor, BullMQ queues

MicroservicesModule (background workers)
├── Same services + repositories (no controllers)
└── BullMQ queue processors

MaintenanceModule (privileged ops)
├── Config, Logging, Storage, Process, Database, User,
│   SystemMetadata, App repos
├── MaintenanceWorkerController
├── DatabaseBackupService
└── MaintenanceAuthGuard

ImmichAdminModule (CLI, no HTTP)
├── All services + repositories
└── nest-commander commands

1.4 immich-machine-learning — Python Service

The ML service runs as a standalone Python/FastAPI application:

• Runtime: Gunicorn (process manager) + Uvicorn (ASGI workers)
• Inference engine: ONNX Runtime
• Default port: 3003 (overridden by IMMICH_PORT)
• Model cache: in-memory with configurable TTL (default 300 seconds)
• ANN: Approximate nearest-neighbor search for fast CLIP embedding lookup

Models used by default:

Hardware acceleration backends (ONNX Runtime execution providers):

1.5 PostgreSQL — Database Layer

Immich requires a custom PostgreSQL image (ghcr.io/immich-app/postgres:14-vectorchord) that ships with vector extensions pre-installed. Using a stock PostgreSQL image will fail at startup.

Important

Always use the Immich-provided PostgreSQL image. The vector extensions (VectorChord, pgvecto.rs, pgvector) are required for smart search and facial recognition. A vanilla PostgreSQL container will not work.

1.6 Redis / Valkey — Queue Broker

• Image: valkey:9
• Role: BullMQ job queue broker only (no application data stored)
• Health check: redis-cli ping
• Losing Redis data does not lose photos or user data — it only loses queued jobs that have not yet been processed. Jobs will be re-queued on next trigger.

1.7 BullMQ Job Queues

All background processing is driven by BullMQ queues backed by Redis. Default concurrency values (tunable via SystemConfig):

Tip

videoConversion runs at concurrency 1 by default — video transcoding is CPU/GPU-bound. Increase this only if you have hardware acceleration configured and sufficient resources.

1.8 Web Frontend — SvelteKit

The web frontend is a SvelteKit application served via SSR from the immich-server process using sirv for static assets. The SvelteKit app uses Svelte 5 runes and file-based routing. It communicates with the backend entirely through the REST API (auto-generated TypeScript SDK from the OpenAPI spec).

1.9 Mobile App — Flutter

The Flutter mobile app (iOS + Android) handles background photo backup, offline viewing, and full-featured library management. The mobile app communicates with the same REST API as the web frontend. OAuth callback URL: app.immich:///oauth-callback.

1.10 CLI — @immich/cli

A separate CLI package built with Commander.js that wraps the auto-generated TypeScript SDK. The CLI is distinct from the immich-admin server-side admin CLI described in Section 5.

2. System Requirements

2.1 Software Requirements

2.2 Hardware Requirements

Minimum (small home deployment):

Notes:

• ML inference (CLIP, face detection) is compute-intensive. Dedicated ML hardware acceleration dramatically reduces processing time for large libraries.
• The PostgreSQL vector index (cube, VectorChord) requires RAM proportional to library size.
• Video transcoding (videoConversion queue) is the most resource-intensive background task. Hardware acceleration (NVENC, QuickSync, VAAPI) is strongly recommended for libraries with significant video content.

2.3 Storage Layout

Default storage paths inside the container:

Override the media root with IMMICH_MEDIA_LOCATION.

Warning

Always bind-mount the media directory to a persistent volume. Container restarts with no volume will destroy all uploaded assets.

3. Configuration Reference

Immich has two layers of configuration:

1. Environment variables — set at container start, control infrastructure connections and runtime behavior
2. SystemConfig — runtime configuration stored in PostgreSQL, editable via the web UI Admin panel or REST API

When IMMICH_CONFIG_FILE is set, runtime configuration is loaded from a YAML/JSON file on disk instead of the database. You cannot update SystemConfig via the UI or API while a config file is in use.

3.1 Server Environment Variables

3.2 Database Environment Variables

Important

Change DB_PASSWORD from the default postgres before exposing Immich to any network. The default credentials are well-known.

3.3 Redis Environment Variables

3.4 Machine Learning Environment Variables

3.5 SystemConfig Reference (Runtime Configuration)

SystemConfig is stored in PostgreSQL and can be edited via the Administration → Settings panel in the web UI. All values below are defaults.

3.5.1 Backup

3.5.2 FFmpeg / Video Transcoding

3.5.3 Job Concurrency

Concurrency for each BullMQ queue is tunable at runtime. See Section 1.7 for defaults.

3.5.4 Logging

3.5.5 Machine Learning

3.5.6 Maps & Geocoding

3.5.7 OAuth / SSO

3.5.8 Password Login

Caution

If you disable both passwordLogin and oauth, users (including admins) will be unable to log in. Use immich-admin enable-password-login to recover.

3.5.9 Storage Template

3.5.10 Image Quality

3.5.11 Trash

3.5.12 Library

3.5.13 Notifications (SMTP)

SMTP notifications are disabled by default. Configure via Administration → Notifications.

3.5.14 Server Behavior

3.5.15 Nightly Tasks

3.5.16 User Management

4. Deployment & Scaling

4.1 Standard Docker Compose Deployment

The canonical production deployment uses docker/docker-compose.prod.yml:

# Key services and ports
services:
  immich-server:
    ports: ["2283:2283"]      # HTTP API + Web UI

  immich-machine-learning:
    ports: ["3003:3003"]      # ML API (internal only)

  redis:
    # Internal only — no exposed port

  database:
    ports: ["5432:5432"]     # PostgreSQL (restrict in production)

  immich-prometheus:
    ports: ["9090:9090"]     # Prometheus (restrict in production)

  immich-grafana:
    ports: ["3000:3000"]     # Grafana (restrict in production)

Minimal production .env:

# Database
DB_PASSWORD=change_me_strong_password
DB_USERNAME=immich
DB_DATABASE_NAME=immich

# Paths
UPLOAD_LOCATION=/path/to/your/media
DB_DATA_LOCATION=/path/to/postgres/data

4.2 Rootless Deployment

docker/docker-compose.rootless.yml adds security hardening:

services:
  immich-server:
    user: '1000:1000'
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - NET_RAW

Use rootless mode whenever the host allows it. Ensure the volume mount paths are owned by UID/GID 1000.

4.3 Splitting Workers for Scale

By default, a single immich-server container runs all three worker types. For high-load deployments, separate them:

# API-only container
IMMICH_WORKERS_INCLUDE=api docker compose up

# Microservices-only container (background jobs)
IMMICH_WORKERS_INCLUDE=microservices docker compose up

Note

When running split workers, all instances share the same PostgreSQL and Redis. The BullMQ queue ensures jobs are processed exactly once — multiple microservices workers safely consume from the same queues.

4.4 Hardware Acceleration — Video Transcoding

Override the base compose file with a hardware acceleration profile:

# NVIDIA GPU (NVENC)
docker compose -f docker-compose.yml -f hwaccel.transcoding.yml --profile nvenc up

# Intel Quick Sync
docker compose -f docker-compose.yml -f hwaccel.transcoding.yml --profile quicksync up

# AMD/Intel VAAPI (Linux)
docker compose -f docker-compose.yml -f hwaccel.transcoding.yml --profile vaapi up

# VAAPI on WSL2
docker compose -f docker-compose.yml -f hwaccel.transcoding.yml --profile vaapi-wsl up

# Rockchip RKMPP
docker compose -f docker-compose.yml -f hwaccel.transcoding.yml --profile rkmpp up

Then set ffmpeg.accel in SystemConfig to match the backend.

4.5 Hardware Acceleration — Machine Learning

# NVIDIA CUDA
docker compose -f docker-compose.yml -f hwaccel.ml.yml --profile cuda up

# AMD ROCm
docker compose -f docker-compose.yml -f hwaccel.ml.yml --profile rocm up

# Intel OpenVINO
docker compose -f docker-compose.yml -f hwaccel.ml.yml --profile openvino up

# Rockchip RKNN
docker compose -f docker-compose.yml -f hwaccel.ml.yml --profile rknn up

# ARM NN
docker compose -f docker-compose.yml -f hwaccel.ml.yml --profile armnn up

4.6 CLIP Model Selection

Immich ships with 40+ supported CLIP models. Models differ in embedding dimensions (512 to 1536), search quality, and inference speed.

Key model families:

Warning

Changing the CLIP model requires re-embedding your entire library. This is a compute-intensive operation. After changing the model in SystemConfig, trigger Jobs → Smart Search → Run All from the admin panel.

4.7 Reverse Proxy Configuration

Set IMMICH_TRUSTED_PROXIES to your reverse proxy's IP/CIDR to enable proper client IP forwarding:

IMMICH_TRUSTED_PROXIES=172.16.0.0/12,192.168.0.0/16

Set server.externalDomain in SystemConfig to the public URL so generated share links are correct.

nginx example:

location / {
    proxy_pass http://immich-server:2283;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 50000M;
    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;
}

The proxy_read_timeout must match Immich's 24-hour request timeout to support large video uploads.

4.8 File-Based Configuration

To use a configuration file instead of database-stored SystemConfig:

IMMICH_CONFIG_FILE=/etc/immich/config.json

{
  "ffmpeg": {
    "crf": 23,
    "preset": "ultrafast",
    "targetVideoCodec": "H264"
  },
  "machineLearning": {
    "enabled": true,
    "clip": { "modelName": "ViT-B-32__openai" }
  }
}

Caution

While IMMICH_CONFIG_FILE is set, the SystemConfig API and admin UI settings panel are disabled. Any attempt to update settings via the API returns: "Cannot update configuration while IMMICH_CONFIG_FILE is in use".

5. Operations

5.1 immich-admin CLI

The immich-admin CLI runs inside the server container and provides privileged administrative operations that bypass the HTTP API. Always use this CLI to recover from authentication lockout scenarios.

docker exec -it immich_server immich-admin <command>

Common recovery workflows:

# Locked out — reset admin password
docker exec -it immich_server immich-admin reset-admin-password

# Disabled password login accidentally
docker exec -it immich_server immich-admin enable-password-login

# Promote a user to admin
docker exec -it immich_server immich-admin grant-admin [email removed]

# Verify DB schema after upgrade
docker exec -it immich_server immich-admin schema-check

5.2 Database Backups

Immich performs automated PostgreSQL backups on the schedule defined in backup.database.cronExpression (default: daily at 2 AM). Backups are stored in the backups/ subdirectory of the media location.

Retention: backup.database.keepLastAmount (default: 14 backups).

Manual backup via Docker:

docker exec immich_postgres pg_dumpall -U postgres > immich_backup_$(date +%Y%m%d).sql

Restore from backup:

docker exec -i immich_postgres psql -U postgres < immich_backup_20260513.sql

Warning

After restoring a database from backup on a new machine, run change-media-location if the media paths differ. Inconsistent paths produce the error: "Detected an inconsistent media location".

5.3 Database Migrations

Migrations run automatically on server startup unless DB_SKIP_MIGRATIONS=true. If the schema check fails:

• Error "Detected schema drift" — see docs.immich.app/errors#schema-drift
• Error "Invalid upgrade path" — see docs.immich.app/errors/#typeorm-upgrade

Never downgrade Immich without restoring a pre-upgrade database backup. Migrations are not reversible.

5.4 Job Management

The admin panel (Administration → Jobs) provides controls to:

• Run, pause, or clear individual queues
• View queue depths and processing status
• Trigger full re-processing (e.g., re-embed all assets for a new CLIP model)

5.5 External Library Management

External libraries allow Immich to index photos from arbitrary filesystem paths without moving files. Configuration:

1. Mount the external path into the container
2. Create a Library in Administration → Libraries
3. Configure path(s) for the library
4. Run a scan (manual or scheduled via library.scan.cronExpression)

Filesystem watching (library.watch.enabled) uses inotify and reacts to changes in real time, but is disabled by default due to resource implications on large libraries.

5.6 Storage Template Migration

Enable storageTemplate.enabled to reorganize files on disk using a date/metadata template. Default template: {{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}.

Caution

Enabling storage templates moves files on disk. Ensure sufficient free space and a working backup before enabling. The migration runs as a background job in the migration queue.

5.7 Telemetry and Metrics

Immich exposes Prometheus metrics when telemetry is configured:

IMMICH_TELEMETRY_INCLUDE=all
IMMICH_API_METRICS_PORT=8081
IMMICH_MICROSERVICES_METRICS_PORT=8082

The production Docker Compose ships with immich-prometheus and immich-grafana pre-configured. Access Grafana at port 3000 to view dashboards for queue depths, job throughput, API latency, and ML processing times.

5.8 Audit Log

Immich maintains an audit log of user actions. The audit log retains events for a maximum of 100 days (AUDIT_LOG_MAX_DURATION).

5.9 Maintenance Mode

Maintenance mode prevents user operations while allowing admin tasks:

docker exec -it immich_server immich-admin enable-maintenance-mode
# ... perform maintenance ...
docker exec -it immich_server immich-admin disable-maintenance-mode

6. Performance

6.1 Database Tuning

The vector extension (VectorChord / pgvecto.rs) drives CLIP search performance. Key tuning parameters for PostgreSQL:

-- Verify extensions are installed
SELECT * FROM pg_extension WHERE extname IN ('vector', 'vectorchord', 'vectors');

-- Check vector index status
SELECT schemaname, tablename, indexname FROM pg_indexes
WHERE indexname LIKE '%embedding%';

PostgreSQL container settings:

• shm_size: 128mb — required for vector operations
• POSTGRES_INITDB_ARGS=--data-checksums — data integrity

For large libraries (100K+ assets), consider increasing shared_buffers and effective_cache_size in postgresql.conf.

6.2 Machine Learning Performance

Model preloading eliminates cold-start latency on first request after restart:

MACHINE_LEARNING_PRELOAD__CLIP=ViT-B-32__openai
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION=buffalo_l

Multi-worker ML (if memory headroom exists):

MACHINE_LEARNING_WORKERS=2

Each Gunicorn worker loads models independently into memory. With 2 workers and both models loaded, expect substantially higher RAM usage.

Thread tuning for CPU-only inference:

# Let ONNX choose (usually best)
MACHINE_LEARNING_MODEL_INTER_OP_THREADS=0
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS=0

# Or pin explicitly for a known CPU
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS=4

ANN (Approximate Nearest Neighbor) is enabled by default and provides near-instant search after the index is built. Disable only to debug search accuracy:

MACHINE_LEARNING_ANN=false

6.3 Queue Concurrency Tuning

Tune job concurrency in SystemConfig based on your hardware:

6.4 FFmpeg Optimization

For quality vs. size tradeoffs in systemConfig.ffmpeg:

# Better quality, larger files
crf: 18, preset: slow

# Balanced (default)
crf: 23, preset: ultrafast

# Smallest files
crf: 28, preset: ultrafast

HDR content: set tonemap to Hable (default), Reinhard, or Mobius depending on your display targets.

6.5 Network and Upload Performance

• Large video uploads are protected by a 24-hour request timeout
• For bulk initial imports, use the CLI upload tool rather than the web UI
• For external libraries on NAS, ensure the mount uses appropriate network filesystem tuning (NFS with noatime, appropriate rsize/wsize)

7. Security

7.1 Authentication Architecture

Immich supports two authentication mechanisms:

Password hashing: bcrypt with SALT_ROUNDS = 10.

Session management: Sessions are tracked in the database. Admins can revoke sessions via Administration → Users → Sessions.

API Keys: Users generate API keys from their profile. Keys are stored as bcrypt hashes.

7.2 OAuth / OIDC Configuration

Immich implements OIDC (OpenID Connect). Configure in Administration → Settings → Authentication:

clientId:      <your OIDC client ID>
clientSecret:  <your OIDC client secret>
scope:         openid email profile
signingAlgorithm: RS256
tokenEndpointAuthMethod: client_secret_post

Auto-registration (oauth.autoRegister: true): New users logging in via OAuth are automatically provisioned. Disable if you want to pre-create all accounts.

Auto-launch (oauth.autoLaunch: false): When true, the login page immediately redirects to the OAuth provider.

Mobile OAuth callback URL: app.immich:///oauth-callback

Important

Known issue (#26839): OAuth account linking fails if email addresses differ in case between the identity provider and Immich. Ensure your IdP sends lowercase email addresses, or normalize on the IdP side.

7.3 HTTP Security Headers

Immich applies Helmet middleware by default, which sets standard security headers including Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and Strict-Transport-Security (when TLS is terminated upstream).

Customize Helmet configuration by providing a JSON file and setting IMMICH_HELMET_FILE.

7.4 Trusted Proxies

When running behind a reverse proxy, set IMMICH_TRUSTED_PROXIES to the proxy's IP range so client IPs are correctly recorded in audit logs:

IMMICH_TRUSTED_PROXIES=10.0.0.1/32,172.17.0.0/16

Without this, all traffic appears to originate from the proxy IP.

7.5 Network Isolation

Production deployments should:

• Expose only port 2283 (via reverse proxy with TLS)
• Keep PostgreSQL (5432), Redis (6379), ML (3003), Prometheus (9090), and Grafana (3000) on internal Docker networks only
• Use rootless containers (docker-compose.rootless.yml) where possible

7.6 Storage Security

• Media files are served with signed download tokens
• Shared links use separate authentication (no user session required)
• Trash retention (trash.days: 30) protects against accidental deletion

7.7 Admin Account Security

• Only one admin account is permitted at initial setup
• Additional admins are promoted via immich-admin grant-admin
• The admin password can be reset via immich-admin reset-admin-password (requires container access)
• Error: "The server already has an admin" prevents multiple admin setups

7.8 Quota Management

Storage quotas are configurable per user. Quota usage is reconciled nightly (nightlyTasks.syncQuotaUsage: true). When a user exceeds their quota, uploads fail with: "Quota has been exceeded!".

8. Developer Internals

8.1 Repository Structure

immich-app/immich/
├── server/                NestJS backend (TypeScript)
│   └── src/
│       ├── controllers/   64 HTTP controllers
│       ├── services/      48 services (extending BaseService)
│       ├── repositories/  58 Kysely-backed repository files
│       ├── commands/      immich-admin CLI commands
│       ├── middleware/    Guards, interceptors, filters
│       ├── schema/        Database schema (Kysely)
│       ├── config.ts      Queue defaults, SystemConfig structure
│       └── constants.ts   App-wide constants
├── web/                   SvelteKit frontend (TypeScript, Svelte 5)
├── mobile/                Flutter mobile app (Dart)
├── machine-learning/      Python ML service
│   └── app/
│       ├── models/        ONNX model wrappers
│       ├── sessions/      ONNX session management
│       └── ann/           ANN index
├── cli/                   @immich/cli (Commander.js)
├── open-api/              OpenAPI spec + TypeScript SDK
├── docker/                Compose files (dev, prod, rootless, hwaccel)
├── e2e/                   End-to-end tests (Vitest + Playwright)
├── i18n/                  Translations (79 locale files)
├── docs/                  Docusaurus documentation site
├── plugins/               Plugin system
└── deployment/            Deployment modules (Cloudflare)

8.2 Service Layer Architecture

All 48 services extend BaseService, which provides access to injected repository instances, Logger, Config, and the event emitter.

Services organized by domain:

8.3 Repository Layer

The 58 repository files implement the data access layer using Kysely — a type-safe SQL query builder:

• CamelCasePlugin — automatically converts snake_case DB columns to camelCase TypeScript properties
• Transactions for multi-step operations
• Repository interfaces enable dependency injection and mocking in tests
• No ORM — raw SQL via Kysely type-safe builder
• Migrations managed via Kysely migrations in server/src/schema/

8.4 API Design

The REST API is defined via NestJS decorators, validated with Zod schemas (ZodValidationPipe), serialized with Zod interceptors (ZodSerializerInterceptor), and documented via auto-generated OpenAPI/Swagger spec.

API categories (from ApiTag enum):

Activities, Albums, ApiKeys, Assets, Authentication, AuthenticationAdmin, DatabaseBackups, Deprecated, Download, Duplicates, Faces, Jobs, Libraries, Maintenance, Map, Memories, Notifications, NotificationsAdmin, Partners, People, Plugins, Queues, Search, Server, Sessions, SharedLinks, Stacks, Sync, SystemConfig, SystemMetadata, Tags, Timeline, Trash, UsersAdmin, Users, Views, Workflows

Authentication on API calls:

x-api-key: YOUR_API_KEY

Or via session cookie for browser-based clients.

8.5 WebSocket Events

Real-time events (upload progress, job status, sync) are pushed via WebSocket. The server uses NestJS's WebSocket adapter on the same port 2283.

8.6 Plugin System

Immich has a plugin architecture (plugins/ directory, PluginService, PluginHostFunctions). External plugins are disabled by default:

IMMICH_ALLOW_EXTERNAL_PLUGINS=true

8.7 OpenAPI SDK Generation

The TypeScript SDK (open-api/) is auto-generated from the server's OpenAPI spec. Both the web frontend and CLI consume this SDK. When developing new API endpoints:

1. Add controller + decorators in server/src/controllers/
2. Run the SDK generation script
3. Update web/CLI clients

8.8 Machine Learning Service Internals

The Python ML service is a FastAPI application:

Session lifecycle:

• Models are loaded on first request
• Sessions are cached in memory
• MACHINE_LEARNING_MODEL_TTL controls eviction of idle models
• MACHINE_LEARNING_MODEL_TTL_POLL_S controls how often the TTL check runs

ANN index:

• Built from CLIP embeddings stored in PostgreSQL
• Provides sub-millisecond search on large libraries
• Exported and reloaded between restarts

8.9 End-to-End Testing

The e2e/ directory contains:

• Vitest — API-level integration tests against a running Immich instance
• Playwright — browser automation tests for web UI flows

Run E2E tests against a local dev stack:

# Start dev environment first
docker compose -f docker/docker-compose.dev.yml up

# Run API tests
cd e2e && npm run test:api

# Run browser tests
cd e2e && npm run test:browser

8.10 Internationalization

79 locale files live in i18n/. The web frontend uses these via SvelteKit's i18n support.

8.11 Key Constants

9. Integration Points

9.1 REST API Access

Base URL: https://your-immich-domain/api

Authentication:

curl -H "x-api-key: YOUR_API_KEY" https://your-immich/api/server/ping

Core endpoint categories:

9.2 @immich/cli — Bulk Operations

The @immich/cli package provides command-line access for bulk operations:

npm install -g @immich/cli

# Configure
immich login https://your-immich/api YOUR_API_KEY

# Bulk upload
immich upload --recursive /path/to/photos/

# Upload to album
immich upload --album "Vacation 2026" /path/to/vacation/

The CLI uses the auto-generated TypeScript SDK and communicates via the same REST API as the web UI.

9.3 Prometheus Metrics Integration

Enable metrics:

IMMICH_TELEMETRY_INCLUDE=all
IMMICH_API_METRICS_PORT=8081
IMMICH_MICROSERVICES_METRICS_PORT=8082

Add to Prometheus scrape_configs:

scrape_configs:
  - job_name: 'immich-api'
    static_configs:
      - targets: ['immich-server:8081']
  - job_name: 'immich-microservices'
    static_configs:
      - targets: ['immich-server:8082']

The production Docker Compose includes pre-configured Prometheus and Grafana services.

9.4 SMTP / Email Notifications

Configure SMTP in Administration → Notifications. Immich can send new device login alerts, shared album invitations, and storage quota warnings via the NotificationService / NotificationAdminService pipeline.

9.5 Webhook Integration

Immich supports outbound webhooks for event notifications, configured in Administration → Webhooks. Webhooks are signed with HMAC for authenticity verification.

9.6 OAuth Provider Integration

Immich works as an OIDC relying party. Configure your identity provider with:

• Redirect URI: https://your-immich/auth/login
• Mobile redirect URI: app.immich:///oauth-callback
• Required claims: email, sub (and optionally name, picture)

10. Troubleshooting

Error: "Password login has been disabled"

Cause: passwordLogin.enabled was set to false and OAuth is not functioning.

Solution:

docker exec -it immich_server immich-admin enable-password-login

Prevention: Test OAuth login before disabling password login. Keep a break-glass admin procedure documented.

Error: "Incorrect email or password"

Cause: Wrong credentials, or account was created via OAuth and has no password.

Solution: Use the OAuth flow if the account was OAuth-created. For admin password reset:

docker exec -it immich_server immich-admin reset-admin-password

Prevention: Ensure users know which auth method their account uses.

Error: "Quota has been exceeded!"

Cause: User's storage quota has been reached.

Solution: Increase or remove the user's quota in Administration → Users → edit user. Or wait for nightly quota sync to reconcile actual usage.

Prevention: Set quotas with sufficient headroom and monitor usage in the admin dashboard.

Error: "OAuth is not enabled"

Cause: Client is attempting OAuth flow but oauth.clientId is not configured.

Solution: Configure OAuth settings in Administration → Settings → Authentication.

Prevention: Validate OAuth configuration before communicating OAuth availability to users.

Error: "The server already has an admin"

Cause: Attempting to run initial setup when an admin account already exists.

Solution: Log in with the existing admin account. If credentials are lost:

docker exec -it immich_server immich-admin reset-admin-password

Prevention: Document admin credentials securely at setup time.

Error: "Cannot update configuration while IMMICH_CONFIG_FILE is in use"

Cause: IMMICH_CONFIG_FILE env var is set, disabling database-backed SystemConfig.

Solution: Edit the config file directly, then restart the server. Or remove IMMICH_CONFIG_FILE to switch back to database config.

Prevention: Choose one config method and document it. Do not mix file-based and database-based config.

Error: "Smart search is not enabled"

Cause: machineLearning.enabled is false, or the ML container is unreachable.

Solution:

# Verify ML container is running
docker ps | grep machine-learning

# Check ML health
curl http://immich-machine-learning:3003/ping

# Check ML container logs
docker logs immich_machine_learning

Verify IMMICH_MACHINE_LEARNING_URL matches the ML container's address.

Prevention: Monitor ML container health. The prod compose includes health checks.

Error: "Detected an inconsistent media location"

Cause: Database records reference file paths that no longer exist on disk (e.g., after moving the media volume).

Solution:

docker exec -it immich_server immich-admin change-media-location

See docs.immich.app/errors#inconsistent-media-location for detailed steps.

Prevention: Always update IMMICH_MEDIA_LOCATION and run change-media-location when migrating storage.

Error: "Detected schema drift"

Cause: The database schema does not match what the current server version expects. Often occurs after a failed migration or manual DB modification.

Solution: See docs.immich.app/errors#schema-drift. Run:

docker exec -it immich_server immich-admin schema-check

Prevention: Never manually modify the Immich database schema. Always upgrade via official Docker images.

Error: "Invalid upgrade path"

Cause: Attempting to upgrade Immich by skipping major versions.

Solution: See docs.immich.app/errors/#typeorm-upgrade. Upgrade through intermediate versions sequentially.

Prevention: Follow the official upgrade guide. Always back up the database before upgrading.

Issue: ML container stuck "unhealthy" after update (GitHub #27228)

Cause: Model cache on disk is incompatible with the new ML version (format change).

Solution:

docker stop immich_machine_learning
# Clear the model cache volume
docker volume rm immich_model-cache
docker start immich_machine_learning
# Wait for models to re-download
docker logs -f immich_machine_learning

Prevention: When updating Immich, check the changelog for ML model cache format changes.

Issue: Faces disappeared (GitHub #27637)

Cause: Re-running face detection with changed thresholds or after a model update can cause re-clustering that loses named assignments.

Solution: Re-assign faces in People view. Consider exporting face assignments before major ML updates.

Prevention: Back up face assignment data before changing facialRecognition settings or ML model versions.

Issue: New photos not appearing on timeline (GitHub #27787)

Cause: Metadata extraction or thumbnail generation jobs are stuck or backed up.

Solution:

1. Check job queue status in Administration → Jobs
2. Look for stuck metadataExtraction or thumbnailGeneration jobs
3. Clear and re-run the affected queues

Prevention: Monitor queue depths via Prometheus/Grafana.

Issue: Android app won't sync, stuck on hashing (GitHub #27846)

Cause: Network timeout or reverse proxy configuration rejecting large uploads.

Solution:

1. Check reverse proxy client_max_body_size — must be large enough for video files
2. Verify proxy_read_timeout is set to at least 86400s to match Immich's 24-hour request timeout
3. Restart the mobile app sync process

Prevention: Configure reverse proxy timeouts appropriately (see Section 4.7).

Issue: OAuth login fails with email case mismatch (GitHub #26839)

Cause: Identity provider sends [email removed] but Immich stored [email removed] at registration.

Solution: Manually update the email in the database to match the IdP exactly, or configure the IdP to always send lowercase email.

Prevention: Normalize email addresses in your IdP to lowercase before they reach Immich.

Issue: Restore on another machine not working (GitHub #27684)

Cause: Media files exist on the old machine but not the new one, or file paths differ.

Solution:

1. Copy media files to the new machine at the same absolute path
2. If paths differ, run change-media-location after restoring the database
3. Verify with schema-check

Prevention: Document exact media paths. Keep media and database backups synchronized.

Issue: Assets cannot be added to album (GitHub #27545)

Cause: Attempting to add partner-owned photos to an album in certain web UI flows.

Solution: Use the asset owner's account to add assets. Album membership for partner assets has known limitations.

Prevention: Design album workflows around asset ownership boundaries.

Issue: Video thumbnails not generating

Cause: FFmpeg unavailable in the container, or video format is unsupported with current transcode settings.

Solution:

# Verify FFmpeg is available
docker exec immich_server ffmpeg -version

# Check microservices logs for errors
docker logs immich_server 2>&1 | grep -i "ffmpeg\|transcode\|thumbnail"

# Re-queue thumbnail generation:
# Administration → Jobs → Thumbnail Generation → Run All

Prevention: Ensure the immich-server image is not modified (FFmpeg is bundled).

Issue: High memory usage in ML container

Cause: Multiple models loaded simultaneously, or MACHINE_LEARNING_WORKERS > 1 with large models.

Solution:

1. Reduce MACHINE_LEARNING_MODEL_TTL to evict models sooner
2. Set MACHINE_LEARNING_WORKERS=1
3. Disable unused ML features in SystemConfig

Prevention: Size ML container memory to hold: (worker count) × (sum of enabled model sizes).

Issue: Database backup failing

Cause: Insufficient disk space in the backup destination, or pg_dumpall timeout.

Solution:

# Check backup directory space
docker exec immich_server df -h /usr/src/app/upload/backups

# Manual backup with compression
docker exec immich_postgres pg_dumpall -U postgres | gzip > backup.sql.gz

Prevention: Monitor disk space. The default 14-backup retention helps but large databases need explicit space planning.

Issue: Port 2283 unreachable after deployment

Cause: Firewall rules, or container failed to start due to missing env vars or Redis/DB connection failure.

Solution:

# Check container status
docker compose ps

# Check server startup logs
docker logs immich_server --tail 100

Prevention: Always verify all required env vars are set before starting. The server logs a clear error for missing database or Redis connections.

Issue: Storage template migration hanging

Cause: Very large library or I/O-bound storage causing slow file moves.

Solution: The migration runs as a background job. Monitor progress in Administration → Jobs → Migration. Do not restart the server mid-migration.

Prevention: Run storage template migration during low-traffic periods. Ensure the migration queue has sufficient concurrency.

Issue: Shared link returns 404 after domain change

Cause: server.externalDomain was not updated to match the new domain.

Solution: Update server.externalDomain in Administration → Settings → Server. Existing share links will use the new domain for future requests.

Prevention: Configure externalDomain from day one. Document domain dependency for any server moves.

Issue: Duplicate detection not finding obvious duplicates

Cause: machineLearning.duplicateDetection.maxDistance threshold may be too low, or smart search embeddings are not yet indexed for all assets.

Solution:

1. Increase maxDistance slightly (e.g., from 0.01 to 0.02)
2. Ensure smart search jobs have completed for all assets
3. Check for stuck smartSearch queue jobs in Administration → Jobs

Prevention: Run a full smart search job after bulk imports before relying on duplicate detection.