Media, checked 2026-10-17
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.3.3,v3.3.1,v3.3.0,v3.2.4 - Licence: AGPL-3.0
- Source: https://github.com/immich-app/immich
- Docs: https://docs.immich.app/
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
| 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
| 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
| 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
| Version | Date | Breaking | What changed | Source |
|---|---|---|---|---|
v3.3.3 | 2026-10-14 | No | Bug fixes, including a major performance improvement for the explore page (people query) and memory dates in every app language. | source for release v3.3.3 |
v3.3.1 | 2026-10-08 | No | Fixes around people sharing and a mobile scroll issue, and adds an indicator showing which people are shared. | source for release v3.3.1 |
v3.3.0 | 2026-10-07 | No | Adds people sharing, birthday memories, auto-stacked mobile edits, OAuth claim sync on every login and new OCR models. | source for release v3.3.0 |
v3.2.4 | 2026-09-28 | No | Small patch that fixes a memory leak through a dependency update and a blank mobile sync status page. | source for release v3.2.4 |
v3.2.0 | 2026-09-10 | No | Adds a docker compose builder, revamped web search UI, search API v2, cross-user people clustering and a dedicated memories page. | source for release v3.2.0 |
If it is not coming up
- ECONNREFUSED / ENOTFOUND / connection to server at "postgres" port 5432 failed
- Coolify volume data lost after redeploy / a new empty volume is created every deploy
- ENOSPC: no space left on device
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-10-17. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.