On this page (5)
The Immich Docker Compose stack is four containers: the server, machine learning, Valkey (the cache, named redis in the file) and Postgres. We first verified the file below on Immich v3.2.4 on Oct 1, 2026, on our earlier sandbox host. On Oct 28 we re-ran it on v3.3.5 on a GitHub Actions runner (2 vCPU, 8 GB); against the v3.3.3 version of this file, only the two Immich tags and their digests changed. v3.3.5 (released Oct 21) is a security release, so a stack on an older tag should move (details under Update safely). The figures are the median of three runs. Its health check passed after 8.6 s (8.5 to 9.5 s). It idled at 1.3 GiB once its memory had settled (1,308 to 1,330 MiB over the runs), used up to 2.1 GiB in its first two minutes, and peaked at 3.6 GiB (range 3.5 to 3.7 GiB) while processing 20 uploaded photos on a 2-vCPU lab host. Plan for 8 GB of RAM. It differs from Immich’s own release file in two ways: named volumes instead of bind mounts, and exact image tags instead of ${IMMICH_VERSION}. Below are the problems we hit, a safe update, and a database backup and restore we ran.
Measured readings
Test box: Immich v3.3.5
Measured in our lab on : 3 full runs, each from a fresh stack. Each figure is the median, with the range over the runs under it. The numbers come from the raw result file.
- Idle RAM
- 1.3 GiBsame when rounded in all 3 runs all containers, median of 3 runs; each run is the mean over 30 s after the stack settled
- Startup peak RAM
- 2.1 GiBrange 2.0–2.1 · 3 runs highest total between healthy and settled
- Peak RAM
- 3.6 GiBrange 3.5–3.7 · 3 runs under load, median of the run peaks
- Settled after
- 174 srange 168–205 · 3 runs after the first healthy response
- Idle CPU
- 3.5 %range 0.8–7.0 · 3 runs of one core, lab host
- Startup
- 8.6 srange 8.5–9.5 · 3 runs to first healthy response
- App version
- v3.3.5
- Tested
- , 3 runs (compose file verified the same day)
- How the figures are made
- Each run starts a fresh stack and goes through setup, settling, the idle window and the load step. We publish the median over the runs and the lowest and highest value, because the lab host and some apps vary from run to run. Runs, median and range
- Lab host
- AMD EPYC 9V45 96-Core Processor, 2 cores, 7.7 GiB RAM, x86_64.Ubuntu 24.04.5 LTS, Docker 28.0.4.
- Disk for the images
- About 4.9 GB with the containerd image store, the default on fresh installs of Docker Engine 29 and later (our estimate: unpacked plus compressed size, plus 10%; not measured on a containerd host). About 3.3 GB with the older overlay2 store (the unpacked column, as measured on this lab host). Plan for the larger figure. How we size disk
- How idle was measured
- After the stack was healthy and set up, we sampled total RAM until it stayed within max(2% of its mean, 10 MiB) over 60 s (at least 120 s, at most 600 s), then measured idle over the next 30 s. Rule in full
- Peak RAM measured
- Under load. Upload 20 generated 4000x3000 JPEGs (about 1 MB each, synthetic gradients and shapes, no people) through the API as the admin user, then wait until every Immich background queue (thumbnails, metadata, CLIP smart search, face detection, ...) is empty. The machine-learning container really runs; the images contain no faces, so face recognition has nothing to find. Peak and mean are taken from the first upload until the queues are idle.
| Container | Idle RAM | Peak RAM (under load) | Image, compressed (download) | Image, unpacked (disk, overlay2 store) |
|---|---|---|---|---|
| database | 380 MiBrange 368–387 · 3 runs | 388 MiBrange 375–394 · 3 runs | 205 MB | 756 MB |
| immich-machine-learning | 204 MiBrange 202–212 · 3 runs | 2.0 GiBrange 1.9–2.0 · 3 runs | 268 MB | 738 MB |
| immich-server | 730 MiBrange 727–732 · 3 runs | 1.2 GiBrange 1.2–1.3 · 3 runs | 609 MB | 1.7 GB |
| redis | 6 MiBrange 5–6 · 3 runs | 8 MiBrange 7–9 · 3 runs | 48 MB | 123 MB |
| Total | 1.3 GiBsame when rounded in all 3 runs | 3.6 GiBrange 3.5–3.7 · 3 runs | 1.1 GB | 3.3 GB |
Every run (3)
| Run | Idle RAM | Peak RAM | Startup peak | Startup | Lab host CPU |
|---|---|---|---|---|---|
| 1 | 1.3 GiB | 3.5 GiB | 2.1 GiB | 9.5 s | AMD EPYC 9V45 96-Core Processor |
| 2 | 1.3 GiB | 3.7 GiB | 2.0 GiB | 8.6 s | AMD EPYC 9V45 96-Core Processor |
| 3 (closest to median idle) | 1.3 GiB | 3.6 GiB | 2.1 GiB | 8.5 s | AMD EPYC 9V45 96-Core Processor |
0 s to 200 s after healthy; the line spans 0 to 2.0 GiB. Dashed line: settled.
Timeline as a table
| Seconds after healthy | Total RAM |
|---|---|
| 30 | 2.0 GiB |
| 60 | 2.0 GiB |
| 90 | 2.0 GiB |
| 120 | 1.3 GiB |
| 150 | 1.3 GiB |
| 180 | 1.3 GiB |
| 200 | 1.3 GiB |
RAM is MiB (220 bytes); image sizes are MB (106 bytes). The unpacked column is what our lab host's Docker reported; see Disk for the images for other setups. Per-container peaks happen at different moments, so they do not add up to the total peak. Medians of separate columns need not add up either.
Download verified compose fileDownload .envRaw result JSONHow we measure
Lab notes (4)
- Warning: immich-server restarted 1 time(s) during the run (run 1 of 3)
- The .env adds IMMICH_HOST=0.0.0.0: the lab host has no IPv6, and the ML container binds [::] by default and crash-loops without it.
- Compose follows the Immich release file with named volumes instead of bind mounts (see the comments in the compose file).
- Hardware acceleration (GPU/iGPU) is not tested: the lab host has none.
Verified compose file
Four services: immich-server, immich-machine-learning, redis and database. The two Immich images are pinned to v3.3.5, Postgres is pinned to Immich’s tested image tag and Valkey is pinned by digest. Only port 2283 is published. The comments in the file are the lab’s.
# Verified compose for Immich, tested 2026-10-28 by the SelfHostBench lab (3 runs; the figures are the median).
# Lab host: AMD EPYC 9V45 96-Core Processor, 2 vCPU, 7.7 GiB RAM, x86_64, Docker 28.0.4.
# Floating image tags below were replaced by the version resolved at test time;
# the registry digest is in the comment on each image line.
# Measurements: immich.json (schema 3).
# Companion env file: immich.env (save it as .env next to this file).
# Secrets are not published: the lab's values are public. In immich.env:
# DB_PASSWORD=CHANGE_ME_DB_PASSWORD. Replace it with your own before the first start.
# Immich: self-hosted photo and video library with machine-learning search.
#
# Based on the compose file of the current Immich release:
# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
# Changes from the release file (everything else is as shipped):
# * the upload and database folders are named volumes instead of the ./library and
# ./postgres bind mounts, so the stack can run on a remote Docker host and `down -v`
# leaves nothing behind. Use bind mounts (UPLOAD_LOCATION / DB_DATA_LOCATION in .env)
# if you want photos in a folder you can see.
# * the extends/hardware-acceleration comments are removed (not tested here).
# Put DB_PASSWORD and friends in the .env file next to this file.
name: immich
services:
immich-server:
container_name: immich_server
image: ghcr.io/immich-app/immich-server:v3.3.5 # sha256:485d546a2e31d6a8b4db8423fcba5c109de8c218d93410af115fd1ccfc4352a6 (version v3.3.5, from label:org.opencontainers.image.version)
volumes:
# Originals, thumbnails, encoded video. This is your photo library: back it up.
- immich-upload:/data
- /etc/localtime:/etc/localtime:ro
env_file:
- .env
ports:
- '2283:2283'
depends_on:
- redis
- database
restart: always
healthcheck:
disable: false
immich-machine-learning:
container_name: immich_machine_learning
# For hardware acceleration, add one of -[armnn, cuda, rocm, openvino, rknn] to the image tag.
image: ghcr.io/immich-app/immich-machine-learning:v3.3.5 # sha256:5b28c9352c8374b8a1ed96fbdd8d6755fea6e43510ec43fdf6538aa02ea40f56 (version v3.3.5, from label:org.opencontainers.image.version)
volumes:
# Downloaded ML models (CLIP, face detection). Safe to delete, they are fetched again.
- model-cache:/cache
env_file:
- .env
restart: always
healthcheck:
disable: false
redis:
container_name: immich_redis
image: docker.io/valkey/valkey:9@sha256:c123e3715db63d06d4ad6964884037aa0d5d4d703939b9929954112889708e1d # version 9.1.2 (from exec); no registry tag for it could be verified, so the digest is pinned instead
healthcheck:
test: redis-cli ping | grep -q PONG || exit 1
restart: always
database:
container_name: immich_postgres
image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0 # sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23 (version 14-vectorchord0.4.3-pgvector0.8.1-pgvectors0.2.0, from label:org.opencontainers.image.version)
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: ${DB_USERNAME}
POSTGRES_DB: ${DB_DATABASE_NAME}
POSTGRES_INITDB_ARGS: '--data-checksums'
# Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
# DB_STORAGE_TYPE: 'HDD'
volumes:
# The Immich database (albums, users, search index). Back this up with pg_dump.
- immich-db:/var/lib/postgresql/data
shm_size: 128mb
restart: always
healthcheck:
disable: false
volumes:
immich-upload:
immich-db:
model-cache:The .env goes next to it. It has two changes from Immich’s example.env: a line for IMMICH_HOST (see the first gotcha below) and no UPLOAD_LOCATION or DB_DATA_LOCATION, because this file uses named volumes. We also left out upstream’s commented TZ line. Add one, such as TZ=America/Chicago, if you want Immich’s nightly 2:00 AM database backup to run on your local time rather than UTC.
# You can find documentation for all the supported env variables at https://docs.immich.app/install/environment-variables
# The Immich version to use. You can pin this to a specific version like "v2.1.0"
IMMICH_VERSION=v3.3.5
# Connection secret for postgres. You should change it to a random password
# Please use only the characters `A-Za-z0-9`, without special characters or spaces
DB_PASSWORD=CHANGE_ME_DB_PASSWORD
# Immich containers listen on [::] (IPv6) by default, and the machine-learning container
# crash-loops on a host whose kernel has IPv6 disabled ("Address family not supported by
# protocol"). The lab host is one of those, so listen on IPv4 only. Harmless on hosts with
# IPv6; delete the line if you like.
IMMICH_HOST=0.0.0.0
# The values below this line do not need to be changed
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immichThe DB_PASSWORD in the downloadable .env is the placeholder CHANGE_ME_DB_PASSWORD, not the password the lab ran with. Postgres accepts that placeholder as an ordinary password (we tried it on the database image), so replace it in step 4 before the first start.
IMMICH_VERSION in this .env does nothing to the image tags. The tags are written into compose.yaml, and docker compose config --images lists them from there. Immich’s upstream file reads IMMICH_VERSION from .env instead. To change versions with ours, edit the two Immich image lines.
Install steps
We ran these steps in a scratch directory on our earlier sandbox host on Oct 1, 2026, with Immich v3.2.x (Docker 29.6.2, Compose 5.3.1). We did not repeat them on v3.3.5 or on the Actions runner; the lab ran the same file on v3.3.5 from a fresh stack. The numbers on this page come from the lab run in immich.json (Oct 28), not from these manual runs.
-
Install Docker Engine with the Compose plugin. Immich’s docs say to use
docker compose(notdocker-compose) and, if you get errors, to install Docker Engine from Docker’s official repository instead of a distro package (Immich install docs). -
Make a folder.
bash mkdir immich-app cd immich-app -
Save the two files above as
compose.yamland.envin that folder. The download links are on each block. -
Replace the placeholder database password (
CHANGE_ME_DB_PASSWORDin the downloaded.env) before the first start. We ran this command on a copy of the published file: the line then held 32 hex characters.bash sed -i "s/^DB_PASSWORD=.*/DB_PASSWORD=$(openssl rand -hex 16)/" .env -
Start the stack. The first start downloads the images: 1,129.8 MB compressed in total on v3.3.5 (table below).
bash docker compose up -d -
Check that all four containers are healthy, then ping the server.
bash docker compose ps --format 'table {{.Name}}\t{{.Status}}' curl -s http://localhost:2283/api/server/pingOur output on v3.2.x, 50 seconds after the start:
text NAME STATUS immich_machine_learning Up 50 seconds (healthy) immich_postgres Up 50 seconds (healthy) immich_redis Up 50 seconds (healthy) immich_server Up 50 seconds (healthy) {"res":"pong"}On that run the ping answered at 20 seconds, while
docker compose psstill showedhealth: starting. Wait for fourhealthyrows. -
Open
http://<host>:2283in a browser. Immich’s post-install page says the first user to register becomes the admin. Not run in our lab: the lab created the admin through the API (setup_admin.pyin the lab repo).
Measured resources
Source: immich.json, three runs on Oct 28, 2026, each from a fresh stack, on the lab host (a GitHub Actions ubuntu-latest runner: 2 vCPU AMD EPYC 9V45, 7.7 GiB RAM, Docker 28.0.4). Every figure below is the median of the three runs, with the range (lowest to highest run) in brackets (why we repeat runs). In each run idle is the mean of 11 samples over 30 s, taken after the stack’s total memory had settled (174 s after the stack was healthy, the median of the three runs, 168 to 205 s over the three; rule on the methodology page) and before any upload. Startup peak is the highest total between healthy and settled. Peak is the highest value seen while the load ran. The load was 20 generated 4000x3000 JPEGs (23.1 MB in total) uploaded through the API, then a wait until every Immich job queue was empty. That took 51.7 s in the median run (51.7 to 54.3 s), with no failed jobs, and a smart search for the images returned all 20 in every run. No run was flagged as varying (the flag needs the highest run to be more than 1.5 times the lowest). Four things differed between runs: settling took 174, 205 and 168 s in the three runs, the load peak was 3,538 MiB in run 1 against 3,802 and 3,701 MiB in runs 2 and 3 (the machine-learning container reached 1,910 MiB in run 1 and 2,075 and 2,055 MiB in the others), the idle window caught a short burst in runs 1 and 2 (a 37.5% CPU sample in the machine-learning container in run 1, a 24.9% sample in the server in run 2, so the mean idle CPU was 7.0%, 3.5% and 0.8% of a core in runs 1 to 3 while idle memory moved by under 2%), and in run 1 immich-server restarted once at start-up. The log of that restart shows a refused database connection (Postgres was not yet accepting connections), not a memory kill; the cause and the other restarts we logged are under Measured resources on the RAM page.
| Container | Idle RAM, settled (MiB) | Startup peak (MiB) | Peak RAM under load (MiB) | Image compressed (MB) | Image unpacked (MB) |
|---|---|---|---|---|---|
| immich-server | 730 (727 to 732) | 1,442 (1,425 to 1,505) | 1,258 (1,253 to 1,350) | 608.7 | 1,680 |
| immich-machine-learning | 204 (202 to 212) | 265 (262 to 272) | 2,055 (1,910 to 2,075) | 268.1 | 738 |
| database (Postgres) | 380 (368 to 387) | 552 (535 to 604) | 388 (375 to 394) | 205.3 | 756 |
| redis (Valkey) | 6 (5 to 6) | 6 (5 to 6) | 8 (7 to 9) | 47.7 | 123 |
| Stack, highest simultaneous total | 1,321 (1,308 to 1,330) | 2,145 (2,083 to 2,167) | 3,701 (3,538 to 3,802) | 1,129.8 | 3,297 |
Each cell is the median of the three runs with the range in brackets. The stack peak is the highest sum of all four containers at one instant, so it is lower than the sum of the per-container peaks (in the median run, 3,701 MiB against 3,710 MiB), and medians of separate columns need not add up. The compressed sizes are registry numbers and carry across hosts. The unpacked sizes are what Docker reports on the lab host, which uses Docker 28.0.4 with the classic overlay2 image store. Docker 29 and later uses the containerd image store on fresh installs, and that store also keeps the compressed layers, so the same images take more disk there: the earlier host (Docker 29.6.2, containerd store) showed 5,026 MB for this stack on v3.2.4, with older image builds, so that is not a like-for-like comparison. For disk we plan for unpacked plus compressed size plus 10%, about 4.9 GB for the images against 3.3 GB on overlay2 (how we size disk). CPU, medians of the three runs; this runner has 2 vCPUs, so 200% is the most a stack can use:
| Container | Idle CPU, mean (% of one core, lab host) | Load CPU, mean (% of one core, lab host) | Load CPU, max (% of one core, lab host) |
|---|---|---|---|
| immich-server | 0.3 | 28 | 178 |
| immich-machine-learning | 0.2 | 52 | 189 |
| database (Postgres) | 0.0 | 0.9 | 12 |
| redis (Valkey) | 0.2 | 0.8 | 4.2 |
| Stack | 3.5 | 81 | 197 |
What the numbers say:
- The machine-learning container is the swing. It held 204 MiB before the upload and reached 2,055 MiB (1,910 to 2,075 over the runs) while it processed the images. On v3.2.4 on the earlier host it held 163 MiB; we do not know whether the version or the host explains that. Immich’s environment variable docs list
MACHINE_LEARNING_MODEL_TTL, the inactivity time before a model is unloaded, with a default of 300 s. On a later 4 GiB-capped v3.2.4 stack on the earlier host it fell back to 166 MiB about 5 minutes after its last model load; see Immich RAM requirements. immich-serveruses about 1.5 GiB for roughly its first two minutes, then drops. In the memory timeline of run 3, the run with the median peak and the median idle (10 s averages; it is the run the Test box draws) the stack total falls from 2,034 MiB at 100 s after healthy to 1,942 MiB at 110 s, 1,319 MiB at 120 s and 1,320 MiB at 130 s and stays there; the server goes from 1,441 MiB at 100 s to 726 MiB at 130 s. All three runs show the same drop (2,037 to 2,063 MiB at 90 s, 1,307 to 1,341 MiB at 140 s). So the server’s startup peak (1,442 MiB) is higher than its peak under load (1,258 MiB), and its settled idle (730 MiB) is lower than both. We did not investigate why it drops. Our figures before Oct 2 (2,162 MiB idle, v3.2.4) were taken inside that first phase; the methodology page explains the change.- By our sizing rule (the highest reading of any run, 3,802 MiB, times 1.5, rounded up to 1, 2, 4, 8, 16 or 32 GB) the stack needs 8 GB. Immich’s requirements page says 6 GB minimum and 8 GB recommended, with 4 GB possible if machine learning is disabled. We ran a version of that afterwards on the 8 GB runner: with machine learning off the stack’s highest reading was 2.1 GiB (in its first two minutes), and it finished the same upload test inside 2 GiB of container memory limits in 3 of 3 runs on each of v3.3.1, v3.3.3 and v3.3.5, though the database came within 2 MiB of its limit at start-up in one of the v3.3.1 runs, within 15 MiB on v3.3.3 and within 18 MiB on v3.3.5. The full stack also finished inside 4 GiB of limits without a kill; on v3.3.5 the machine-learning container peaked 171 MiB under its limit in the median run and 94 MiB under in the highest (30 and 27 MiB under on v3.3.3, 5 and 2 MiB under on v3.3.1), a wider margin than before but still one test of 20 photos, so we do not call 4 GiB safe with machine learning on. None of this is a real 4 GB or 2 GB machine. The runs, the caps, the earlier host’s results (where the same 4 GiB limits killed a machine-learning worker in 8 of 8 runs) and where our numbers differ from the docs are on the Immich RAM requirements page.
- v3.3.5 (released Oct 21, 2026) is a patch release and a security release (see Update safely). v3.3.4 (Oct 20), v3.3.3 (Oct 14), v3.3.1 and v3.3.0 came before it. We did not test a v3.3.2: its release page returned 404 when we looked on Oct 21. We did not run v3.3.4 on its own either; v3.3.5 contains it. The release notes’ memory-related items for v3.3.0 (an opt-in machine-learning model revision described as using less memory, thumbnail resampling) and what we read in the later notes are summarized under What changed in v3.3.0, v3.3.1, v3.3.3, v3.3.4 and v3.3.5; we did not set the new model revision.
What we did not measure: libraries of thousands of photos or any video transcoding, face recognition on real faces (the generated images have none), hardware acceleration (the lab host has no GPU), and ARM hosts. A real import will use more than our 20-photo run.
Gotchas, upgrade and backup
The manual checks in this section ran on Immich v3.2.x on our earlier sandbox host (Oct 1, 2026). We did not repeat them on v3.3.5 or on the Actions runner.
The machine-learning container crash-loops without IPv6
On the earlier sandbox host, whose kernel has no IPv6, the first start with Immich’s default settings left immich_machine_learning restarting. The server stayed healthy and answered the ping, so the stack looked fine apart from one container. It kept restarting for as long as we watched. The log (docker compose logs --no-color immich-machine-learning) repeated this:
ERROR connection to ('::', 3003) failed: [Errno 97]
Address family not supported by protocolWe ran Immich’s own release file with IMMICH_VERSION=v3.2.4 for this. Adding IMMICH_HOST=0.0.0.0 to .env and running docker compose up -d again fixed it: all four containers healthy, zero restarts. The environment variable page lists IMMICH_HOST (“listening host”, default 0.0.0.0) for both the server and machine learning, yet our log shows the container trying ::, so set it explicitly. That is why the .env above carries the line, and the v3.3.0, v3.3.1, v3.3.3 and v3.3.5 lab runs used it too. The environment variable docs at v3.3.0 still list IMMICH_HOST (“Listening host”; we did not re-read them at v3.3.1 or v3.3.3). It makes the containers listen on IPv4 only. Not tested in our lab: a host with working IPv6 (we did not check whether the Actions runner has it, or whether v3.3.5 still needs the line), or an IPv6-only host.
The database password is read once
Immich’s docs say to replace the default postgres password with a random one using only A-Za-z0-9; our downloadable .env carries a placeholder there. Do it before the first start (step 4). We changed DB_PASSWORD in .env on a running stack and ran docker compose up -d. The server could not start: password authentication failed for user "postgres". Putting the old value back and running docker compose up -d again brought the stack back. The database kept the password it was created with, so a later change in .env only changes what the server sends. The compose file does not publish port 5432, so the database is reachable only from the other containers.
Named volumes and bind mounts
Our file keeps photos, the database and the model cache in three named volumes (immich_immich-upload, immich_immich-db, immich_model-cache). The immich_ prefix is the project name, which the file fixes with name: immich, so it does not depend on your folder name. Setting COMPOSE_PROJECT_NAME or -p overrides it, so run docker volume ls if you did. Immich’s release file uses two bind mounts, UPLOAD_LOCATION and DB_DATA_LOCATION, which Immich’s example.env sets to ./library and ./postgres. Both work.
- Named volumes needed no permission changes in our runs. The files live under Docker’s data directory, not in a folder you chose.
- Bind mounts put photos in a path you pick, such as a data disk. The Postgres container makes
./postgresowned by its own user (UID 999 in our run) with mode 700, so you need root to browse or delete it. Immich’s requirements page says the database should be on local SSD storage, never a network share, and not on NTFS or FAT filesystems.
The difference matters for docker compose down -v. Docker removes the named volumes declared in the compose file with -v (docker compose down). With our file, down -v removed all three volumes, photos included. With upstream’s bind-mount file, it removed only immich_model-cache. Use plain docker compose down on a stack you want to keep. If you edit our file to use bind mounts, change the two volume lines yourself: we ran upstream’s bind-mount file, not an edited copy of ours.
Update safely
Immich’s upgrade page says to read the release notes and account for breaking changes before upgrading, and that breaking changes are posted in the project’s GitHub discussions. It also says the server is only compatible with the matching major version of the mobile app and that mobile clients should be upgraded first. It states that downgrading is not supported, so the database backup below is your only way back. Read the notes for the version you move to on the releases page. The v3.3.0 notes describe a minor release, the v3.3.1 notes a patch release, the v3.3.3 notes another with two fixes, and the v3.3.4 notes a fourth with two (a missing translation and a faster person query). The v3.3.5 notes, released Oct 21, 2026, are a security release: a Security section lists two dependency updates (the Python base image digests and the certifi package, v2026.10.19), and the intro says the release has “a fix for today’s CA compromise” and “some nodejs security patches” and recommends that you “update as soon as possible”, while saying the authors do not believe the compromise brings an immediate danger to Immich instances. That is the notes’ wording as a web-fetch tool returned it on Oct 29, 2026, and we did not test what the fixes change, so if you run an older tag, read the notes and update. We read no breaking-change section in any of these notes (also through a web-fetch tool, so unverified), and the upgrading page says breaking changes are meant for major versions. Compare the image lines in your compose.yaml with the release’s own docker-compose.yml too: the upgrade page describes a past database migration to VectorChord, so the database image can change between releases. Between v3.2.4 and v3.3.0 the only change in the release file that reached ours was the Valkey digest (the database image was unchanged); between v3.3.0 and v3.3.1 nothing in the release file reached ours (we compared them on Oct 15, lab/notes/release-check-2026-10-15.md), and the same holds for v3.3.3 (compared on Oct 21, lab/notes/patch-batch-2026-10-21.md). For v3.3.5 we read only the release’s docker-compose.yml (through a web-fetch tool on Oct 29): it has the same Valkey and database digests as ours and still a plain depends_on list.
The steps, in order:
-
Back up the database (next section).
-
Change the tags of the two Immich images in
compose.yaml. The update we ran, on the earlier sandbox host on Oct 1, went from v3.2.2 to v3.2.4, so replace both version numbers with yours (for examplev3.2.4tov3.3.5, which we did not run as an update):bash sed -i 's/:v3\.2\.2/:v3.2.4/' compose.yaml -
Pull and restart.
bash docker compose pull docker compose up -d -
Confirm the version.
bash curl -s http://localhost:2283/api/server/versionOn that Oct 1 update the output was
{"major":3,"minor":2,"patch":4,"prerelease":null}, and the admin account created on v3.2.2 could log in. Only the server and machine-learning containers were recreated. Not run in our lab: the update from v3.2.4 to v3.3.5 (or from v3.3.0, v3.3.1 or v3.3.3) on a stack with data; the lab started fresh v3.3.5 stacks.
If you use Immich’s own file, the version is IMMICH_VERSION in .env, and the documented update is docker compose pull && docker compose up -d. Not run in our lab as an update on that file. We pin an exact tag rather than v3: Immich’s docs offer v3 or an exact version, and a major-version tag can point at a newer release the next time you pull.
Back up and restore the database
Immich’s backup page says the database dump holds only metadata, so you also need the upload folder, and to back up the database first and the filesystem second. It also says Immich writes automatic database dumps into UPLOAD_LOCATION/backups (daily at 2:00 AM, keeping 14, by default). With our file that folder sits in the same volume as your photos, so it does not protect against losing the volume.
Dump the database and copy the upload volume out of the running server container. postgres and immich are the defaults of DB_USERNAME and DB_DATABASE_NAME in .env; change them here if you changed those:
mkdir -p backups
docker exec immich_postgres pg_dump --clean --if-exists --dbname=immich --username=postgres | gzip > backups/immich-db.sql.gz
docker cp immich_server:/data ./backups/immich-uploadThe documented command uses docker exec -t. In our run, -t added a carriage return to every line of the dump (238,712 of them). That dump still restored with exit code 0, but a fresh dump of the restored database differed from the original in 26 trigger-function bodies, which now contained carriage returns. No table data differed. Without -t there were none, so we use the command without it. docker cp is fine for a small library; for a large one use a backup tool.
The restore is Immich’s documented procedure with three changes. The documented first line is docker compose down -v, which would delete the upload volume in our file, so we use docker compose down and remove only the database volume. We drop the documented docker compose pull because the images are pinned. The restore needs a database that no Immich server has touched, so the server container is created but not started until the restore finishes.
Warning: docker volume rm immich_immich-db permanently deletes the current database. Run it only after you have checked that backups/immich-db.sql.gz exists and is not empty. If the volume does not exist, as on a new machine, the error is harmless.
docker compose down
docker volume rm immich_immich-db
docker compose create
docker start immich_postgres
sleep 10
gunzip --stdout backups/immich-db.sql.gz | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" | docker exec -i immich_postgres psql --dbname=immich --username=postgres --single-transaction --set ON_ERROR_STOP=on
docker compose up -dpsql exited 0, all four containers came back healthy, and the restored server accepted the admin login created before the dump. The server statistics still counted the photo we had uploaded before the dump. We ran the full cycle on v3.2.4 on Oct 1, 2026, with a stack holding one admin account and one uploaded image.
The database dump holds no photos. To restore them as well, for example after docker compose down -v or on a new machine, copy the upload backup into the server container after docker compose create and before docker compose up -d:
docker cp ./backups/immich-upload/. immich_server:/dataWe ran this after docker compose down -v had removed all three volumes, with the database restored from the dump as above. The uploaded photo’s original and thumbnail then loaded from the API. These copies sit on the same host. A backup tool can move them elsewhere on a schedule, and our restic vs Borg vs Kopia comparison measures restic, Borg and Kopia on a 334 MB generated dataset (not on Immich data, and not at the scale of a photo library).
The same check, a restore into a fresh volume followed by a login that must work, is how we tested a SQLite password vault behind a reverse proxy in Vaultwarden Docker Compose. On a Postgres-backed file server, Nextcloud Docker Compose, the same drill failed on the first try: a plain pg_dump did not carry the database role the app connects as.
Where to run it
- Hardware. Immich idled at 1.3 GiB and peaked at 3.6 GiB under load (medians of 3 runs) in our lab. The highest reading in any run was 3.7 GiB. Plan for at least 8 GB of RAM, sized from the highest run. See Immich RAM requirements, measured.
- VPS. The smallest plan that runs this comfortably has 8 GB of RAM, plus disk for your data and the images. Plan for about 4.9 GB for the images (Docker 29 and later with the containerd image store, the default on fresh installs; 3.3 GB with the older overlay2 store).
- Keep it safe. Back up the data volume before you rely on it, and put the app behind a reverse proxy with HTTPS before you expose it to the internet. See backing up self-hosted apps.
How we size: recommended RAM is the highest reading in any of our runs (under load or during startup, not the median) times 1.5, rounded up to the next of 1, 2, 4, 8, 16 or 32 GB. The extra half covers the operating system, Docker, file cache and spikes our sampling can miss. Your own data and extra apps need more. Disk for images: Docker Engine 29 and later uses the containerd image store on fresh installs, which keeps each image twice (as downloaded and unpacked); older installs use overlay2, which keeps it unpacked only. We plan for the larger figure: unpacked plus compressed size, plus 10%, rounded up. Your data volumes and growth come on top.
Related
- How the lab measures RAM, CPU and image sizes: methodology.
- Other apps in the same format: the self-hosted apps index. For files and sync rather than photos, see the Nextcloud Docker Compose guide, or the measured RAM of three file servers in Nextcloud vs ownCloud vs Seafile. To replace Google Drive rather than Google Photos, see the self-hosted alternative to Google Drive comparison. For a film and TV library with software-transcode numbers, see the Jellyfin Docker Compose guide.
- Official sources used on this page: the Immich install, requirements, upgrading and backup and restore docs.
Update log
- Re-tested on Immich v3.3.5 (was v3.3.3), median of 3 runs on Oct 28; no config changes (Immich tags and digests only). Idle 1,321 MiB (range 1,308 to 1,330; was 1,324), peak 3,701 MiB (range 3,538 to 3,802; was 3,685), startup peak 2,145 MiB (was 2,178), queues idle after 51.7 s (was 57.6), health check after 8.6 s (was 8.6). The sizing figure uses the highest run (3,802 MiB; was 3,726) and still gives 8 GB. v3.3.5 (Oct 21) is a security release: its notes list two dependency updates under Security, say it contains a fix for the CA compromise of that day and some Node.js security patches, and recommend updating as soon as possible (read through a web-fetch tool, so unverified); v3.3.4 (Oct 20) fixed a missing translation and made person queries more efficient. We ran v3.3.5 and not v3.3.4. The host changed as well: an AMD EPYC 9V45 (was an Intel Xeon 6973P-C), on a newer runner image with kernel 7.0 both times, so we do not credit the differences to the version. Image downloads 1,129.8 MB (was 1,135.5), unpacked 3,297 MB (was 3,315). Run 1 had one immich-server restart (a refused database connection at start-up, no memory kill). The manual install, update, backup and restore steps are from v3.2.x and were not repeated.
- Re-tested on Immich v3.3.3 (was v3.3.1), median of 3 runs; no config changes (Immich tags and digests only). Idle 1,324 MiB (range 1,296 to 1,338; was 1,424), peak 3,685 MiB (range 3,352 to 3,726; was 3,349), startup peak 2,178 MiB (was 2,239), queues idle after 57.6 s (was 48.2), health check after 8.6 s (was 9.7). The sizing figure uses the highest run (3,726 MiB; was 3,635) and still gives 8 GB. Version and host changed together: the runs landed on an Intel Xeon 6973P-C (was AMD EPYC 9V74) on a newer runner image with kernel 7.0, so we do not credit the differences to the version. Image downloads 1,135.5 MB (was 1,135.4). Run 1 had one immich-server restart (a refused database connection at start-up, no memory kill). The v3.3.3 release notes list two fixes, one a people-query performance change, and no breaking change, security fix or migration. v3.3.4 (Oct 20) was released before our runs and was not tested. The manual install, update, backup and restore steps are from v3.2.x and were not repeated.
- Linked the new restic vs Borg vs Kopia page from the backup section (a measured comparison of three backup tools on one generated dataset). No measurements changed.
- Linked the new Google Drive alternatives page from Related (files rather than photos). No measurements changed.
- Linked the new Nextcloud vs ownCloud vs Seafile page from Related (file servers rather than photos). No measurements changed.
- Re-tested on Immich v3.3.1 (was v3.3.0), median of 3 runs; no config changes (Immich tags and digests only). Idle 1,424 MiB (range 1,354 to 1,450; was 1,380), peak 3,349 MiB (range 3,348 to 3,635; was 3,546), startup peak 2,239 MiB (was 2,205), queues idle after 48 s (was 54), health check after 9.7 s (was 12.1). The sizing figure uses the highest run (3,635 MiB; was 3,667) and still gives 8 GB. Run 1 had one immich-server restart (a refused database connection at start-up, no memory kill). The title and description changed (SEO test from the Oct 2026 audit; was "Immich Docker Compose: Verified v3.3.0 File and RAM"). The manual install, update, backup and restore steps are from v3.2.x and were not repeated.
- Disk sizing now covers both Docker image stores: plan for about 4.9 GB for the images (unpacked plus compressed size plus 10%, for Docker 29 and later with the containerd store), 3.3 GB on overlay2; was 3.3 GB only. No new measurements.
- Re-tested on Immich v3.3.0 (was v3.2.4) on our new standard lab host (GitHub Actions runner, 2 vCPU / 8 GB), median of 3 runs. The earlier numbers came from a sandbox host with 4 vCPU and 15.7 GiB, so version and host changed together. Idle 1,380 MiB (range 1,378 to 1,400; was 1,321), peak 3,546 MiB (range 3,395 to 3,667; was 3,454), startup peak 2,205 MiB (was 2,244), queues idle after 54 s (was 39; fewer vCPUs). Image downloads 1,135 MB (was 1,208): the machine-learning image is smaller. The sizing figure uses the highest run (3,667 MiB) and still gives 8 GB. The compose file changed only in the Immich tags (v3.3.0, new digests) and the Valkey digest (9.1.2, was 9.1.1). The manual install, update, backup and restore steps are from v3.2.x on the earlier host and were not repeated.
- Results re-measured as the median of 3 runs (methodology change 2026-10-06): idle 1,321 MiB (range 1,316 to 1,370), peak 3,454 MiB (range 3,303 to 3,458), startup peak 2,244 MiB, queues idle after 39 s. Before: 1,364 and 3,409 MiB from one run. Same Immich v3.2.4 and image digests; the sizing figure uses the highest run (3,458 MiB) and still gives 8 GB. The compose file is unchanged.
- Linked the new Jellyfin Docker Compose page from Related (a media server rather than a photo library). No measurements changed.
- Linked the new Nextcloud Docker Compose page from the backup section and Related (files rather than photos). No measurements changed.
- The downloadable .env no longer carries the lab's database password: DB_PASSWORD is the placeholder CHANGE_ME_DB_PASSWORD, to be replaced in step 4. The lab ran with the old value; measurements are unchanged.
- Linked the new Vaultwarden Docker Compose page from the backup and restore section.
- Re-tested under the new idle-RAM method (we now wait for memory to settle). Idle RAM is 1,364 MiB, was 2,162; peak 3,409 MiB, was 3,324. Compose file re-verified, unchanged.
- Linked the new Immich RAM requirements page; replaced the untested 4 GB and model-unload notes with its results.
- First published. Compose file verified on Immich v3.2.4; update, backup and restore steps run on the same day.