Immich Docker Compose Setup (Version-Pinned, Update-Safe)

Guide · Immich

Affiliate links. Disclosure

Pinned version: Immich v3.3.5 (latest GitHub release, published 2026-10-22 03:12 JST / 2026-10-21 18:12 UTC — https://github.com/immich-app/immich/releases/tag/v3.3.5). Last checked: 2026-10-24.

Immich's docs recommend Docker Compose for production. To install it, download the release's docker-compose.yml and example.env, set UPLOAD_LOCATION, DB_PASSWORD and IMMICH_VERSION in .env, run docker compose up -d, and open the web interface on port 2283. Pin the version so updates happen only when you choose.

Immich is a self-hosted photo and video library. Its docs call Docker Compose "the recommended method to run Immich in production" (docs).

Before you start: requirements

From the official requirements page:

If your distro ships an old Docker package, the Immich docs point you to Docker's official install guide, including the "Uninstall old versions" step (Docker Engine install).

Step 1 — Download the compose and env files

These are the official commands. They always fetch the files from the latest release:

bash
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

To match v3.3.5 exactly: the v3.3.5 release attaches both files, so you can use the release-specific URLs. This is the same GitHub URL pattern as above with the version tag in place of latest. The Immich docs don't print these URLs themselves; they come from the release's asset list:

bash
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/download/v3.3.5/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/download/v3.3.5/example.env

Step 2 — Edit .env

The default example.env contains (abridged):

env
UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres
# TZ=Etc/UTC
IMMICH_VERSION=v3
DB_PASSWORD=postgres
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

What to change:

env
IMMICH_VERSION=v3.3.5

Source: the comment in the official example.env reads "You can pin this to a specific version like \"v2.1.0\"" (docs). In the v3.3.5 docker-compose.yml, the server and machine-learning images both use ${IMMICH_VERSION:-release} as their tag, so this one variable pins both.

Step 3 — Start Immich

bash
docker compose up -d

Troubleshooting from the official docs:

Step 4 — First login

The v3.3.5 docker-compose.yml publishes port 2283:2283 on the immich_server container. According to the official post-install steps, "the first user to register will be the admin user". To register, open http://<MACHINE_IP>:2283 and click Getting Started.

Register your admin account right after the first start, because the first person to register becomes admin. Port 2283 serves plain HTTP. Don't forward it to the internet without a reverse proxy with HTTPS, and keep DB_PASSWORD changed from the default.

Upgrading safely

From the upgrading docs:

  1. Read the release notes and the list of breaking changes.
  2. Take a backup first (see our backup & restore guide).
  3. Update IMMICH_VERSION in .env, then run:
bash
docker compose pull && docker compose up -d
docker image prune  # optional: removes old images

Immich follows semantic versioning and intends to keep breaking changes to major releases. The server only works with mobile apps of the matching major version (the app usually supports the current and the prior major), so the docs recommend upgrading mobile clients before the server.

Related: check your hardware first · size your server · import Google Photos

Sources

Related guides