Media, checked 2026-09-07

Immich: Docker configuration reference

Self-hosted photo and video backup with mobile auto-upload, face recognition and machine-learning search.

At a glance

Image: ghcr.io/immich-app/immich-server
Tags: release, v3.2.0-rc.3, v3.1.0, v3.0.3, v3.0.0
Licence: AGPL-3.0
Source: https://github.com/immich-app/immich
Docs: https://docs.immich.app/

Ports

Ports
Port	What listens	Source
`2283` (immich-server)	HTTP listener for the web UI, API and mobile app sync. Route the reverse proxy here.	source for port 2283

Environment variables

Environment variables
Variable	Required	What it does	Example	Source
`UPLOAD_LOCATION`	Yes	Host path for uploaded photos and videos, mounted into the server container at /data.	`./library`	source for UPLOAD_LOCATION
`DB_DATA_LOCATION`	Yes	Host path for the Postgres data files. Network shares are not supported for the database.	`./postgres`	source for DB_DATA_LOCATION
`DB_PASSWORD`	Yes	Postgres connection password, passed straight through to the database container as POSTGRES_PASSWORD.	`postgres`	source for DB_PASSWORD
`IMMICH_TRUSTED_PROXIES`	No	Comma-separated list of proxy IPs the API server trusts for forwarded-header handling.	`172.18.0.1`	source for IMMICH_TRUSTED_PROXIES
`IMMICH_MEDIA_LOCATION`	No	In-container media path, defaults to /data. The docs warn not to change this; use UPLOAD_LOCATION instead.		source for IMMICH_MEDIA_LOCATION

Volumes that must persist

Volumes
Path	What is in it	Source
`/data` (immich-server)	The photo and video library, mapped from the host path set in UPLOAD_LOCATION. The core data to back up.	source for /data
`/var/lib/postgresql/data` (database)	Postgres data directory holding albums, users, face and search metadata, mapped from DB_DATA_LOCATION.	source for /var/lib/postgresql/data
`/cache` (immich-machine-learning)	Downloaded machine-learning models. Safe to lose; it is re-downloaded on next start.	source for /cache

Behind a reverse proxy

Immich must be served at the root of a domain or subdomain. A sub-path such as /immich is not supported. source for this reverse-proxy note
Forward Host, X-Real-IP, X-Forwarded-Proto and X-Forwarded-For, and raise the proxy's max upload size beyond its default. source for this reverse-proxy note
The web client needs a websocket upgrade on the connection; the nginx example sets Upgrade and Connection headers for this. source for this reverse-proxy note
If a proxy issues its own Let's Encrypt HTTP-01 challenge, route /.well-known/immich to the server or the mobile app can lose its connection. source for this reverse-proxy note

What it needs alongside it

Dependencies
Dependency	Why	Source
immich-machine-learning	Separate container that runs face detection, CLIP search and other ML inference the server calls over the internal network.	source for immich-machine-learning
PostgreSQL 14 with the VectorChord or pgvector extension	Primary database, shipped as immich-app's own postgres image with the vector-search extension already installed.	source for PostgreSQL 14 with the VectorChord or pgvector extension
Valkey (Redis-compatible) 9	Job queue used to coordinate background processing between the server and the machine-learning worker.	source for Valkey (Redis-compatible) 9

Release timeline

Releases
Version	Date	Breaking	What changed	Source
`v3.2.0-rc.3`	2026-09-04	No	Third release candidate of v3.2, mainly bug fixes ahead of the stable release.	source for release v3.2.0-rc.3
`v3.1.0`	2026-07-29	No	Adds upload wakelock on web, undo archive, filtering assets by server filepath in workflows and OIDC role claim sync.	source for release v3.1.0
`v3.0.3`	2026-07-15	No	Bug fixes. Notes that F-Droid users must switch to the project's own F-Droid repo going forward.	source for release v3.0.3
`v3.0.1`	2026-07-02	No	Fixes albums not showing up in the mobile app on v2 clients after the v3.0.0 upgrade.	source for release v3.0.1
`v3.0.0`	2026-07-02	Yes	Major version with several breaking changes; the release notes link a dedicated migration guide to follow before upgrading.	source for release v3.0.0

If it is not coming up

Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-09-07. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.

Other app references

All app references