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

Guide · Immich · Doc-based

Doc-based, not yet hands-on tested. This guide is written from the official documentation and has not yet been tested hands-on by us. Check the current official docs before running anything.

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.

Transparency note: This guide is based on the official documentation linked below. It was not hands-on tested by us. Commands are copied from the official docs as of the date above; always check the current docs before running them.

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:

This page contains affiliate placeholders. See our affiliate disclosure.

[AFFILIATE: Amazon Associates — mini PC / SSD for a home server] [AFFILIATE: DigitalOcean or Hostinger — VPS option, check plan RAM against the 6 GB minimum]

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.

⚠️ Caution (not tested by us): 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.

Sources

Related