---
title: 'uprade immich to version 3'
url: 'https://willifix.net/blog/uprade-immich-to-v3'
markdown: 'https://willifix.net/blog/uprade-immich-to-v3.md'
date: '2026-07-11'
description: "A few days ago, immich Version 3 was released https://github.com/immich-app/immich/releases#release-v3.0.2. I've been using Version 2 of the media gallery for a long time. Unfortunately, the previous method using the familiar commands docker compose pull and docker compose up -d --force-recreate fa…"
---

## [uprade immich to version 3](https://willifix.net/blog/uprade-immich-to-v3)

    11th Jul 2026  

A few days ago, immich Version 3 was released [https://github.com/immich-app/immich/releases#release-v3.0.2](https://github.com/immich-app/immich/releases#release-v3.0.2?target=_blank). I've been using Version 2 of the media gallery for a long time.
Unfortunately, the previous method using the familiar commands `docker compose pull` and `docker compose up -d --force-recreate` failed. The immich-server process reported errors related to a vector engine. The Upgrade Documentation [https://docs.immich.app/install/upgrading/](https://docs.immich.app/install/upgrading) gives me some breadcrumbs to follow.

After doing some research, I found the cause. My `Postgres` database didn't have the necessary feature. Here, I'll show you how to upgrade from immich v2 to v3. I also just completed the upgrade from `Postgres` 14 to version 18. I also replaced the `Redis` cache with `valkey`.

### howto

1. open your existing `docker-compose.yml` and change the postgres image to a version that has the needed vector stuff:

    ```
    database:
    container_name: immich_postgres
    # image: registry.hub.docker.com/tensorchord/pgvecto-rs:pg14-v0.2.0@sha256:90724186f0a3517cf6914295b5ab410db9ce23190a2d9d0b9dd6463e3fa298f0
    │   image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    environment:
        POSTGRES_PASSWORD: ${DB_PASSWORD}
        POSTGRES_USER: ${DB_USERNAME}
        POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
        - pgdata:/var/lib/postgresql
    restart: always
    ```
2. recreate and start the containers and wait until immich is up and healthy

    ```
    docker compose up -d --force-recreate
    ```
3. stop the containerstack

    ```
    docker compose down
    ```
4. change the Variable **IMMICH\_VERSION** in the `.env` file to v3

    ```
    # The Immich version to use. You can pin this to a specific version like "v1.71.0"
    IMMICH_VERSION=v3
    ```
5. pull the images and then fire up version 3

    ```
    docker compose pull
    docker compose up -d --force-recreate
    ```

from here on, you have a running instance of immich version 3. However, I think it makes sense to also upgrade the database and the Redis cache to a more recent version.

### Optional todos:

#### upgrade to newer Postgres

1. create a backup of your Database via the webgui of immich. see [https://docs.immich.app/administration/backup-and-restore/](https://docs.immich.app/administration/backup-and-restore?taget=_blank) for more Details > Go to **Administration** > Job Queues
    > Click **Create job** in the top right
    > Select **Create Database Backup** and click Confirm

the backup may take a while; please wait until it's finished.

2. check the backuplocation ./library/backups for existing backup of your database.
3. stop the immich instance with `docker compose down`
4. remove the immich\_pgdata volume with `docker volume rm immich_pgdata`
5. change the database image in the `docker-compose.yml` and the path of pgdata

    ```
    database:
    container_name: immich_postgres
    # image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    image: ghcr.io/immich-app/postgres:18-vectorchord0.5.3-pgvector0.8.1
    environment:
        POSTGRES_PASSWORD: ${DB_PASSWORD}
        POSTGRES_USER: ${DB_USERNAME}
        POSTGRES_DB: ${DB_DATABASE_NAME}
     volumes:
        - pgdata:/var/lib/postgresql
    restart: always
    ```
6. start the database container with `docker compose up database -d`
7. restore the backup:

    ```
    gunzip --stdout "/path/to/backup/dump.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=<DB_DATABASE_NAME> --username=<DB_USERNAME> --single-transaction --set ON_ERROR_STOP=on  # Restore Backu
    ```
8. start immich stack with ``docker compose up -d`

Now you should be up and running with Postgres 18.

#### upgrade redis-cache

1. replace your redis block in `docker-compose.yml` file:

    ```
    redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9@sha256:4963247afc4cd33c7d3b2d2816b9f7f8eeebab148d29056c2ca4d7cbc966f2d9
    healthcheck:
        test: redis-cli ping || exit 1
    restart: always
    ```
2. restart the stack `docker compose up -d --force-recreate`

here is the complete `docker-compose.yml`

  docker-compose.yml```
#
# WARNING: Make sure to use the docker-compose.yml of the current release:
#
# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
#
# The compose file on main may not be compatible with the latest release.
#

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
      - /archiv/Bilderplatte/:/archiv
    env_file:
      - .env
    depends_on:
      - redis
      - database
    restart: always
    labels:
      traefik.enable: "true"
      traefik.http.routers.immich.tls.certresolver: "LE"
      traefik.http.routers.immich.tls: "true"
      traefik.http.routers.immich.rule: "Host(`immich.willifix.net`)"
      traefik.http.routers.immich.entrypoints: "websecure"
      traefik.http.routers.immich.middlewares: "rafficontact@docker"
      traefik.http.services.immich.loadbalancer.server.port: 2283
      traefik.docker.network: "immich_default"

  immich-machine-learning:
    container_name: immich_machine_learning
    # For hardware acceleration, add one of -[armnn, cuda, openvino] to the image tag.
    # Example tag: ${IMMICH_VERSION:-release}-cuda
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    # extends: # uncomment this section for hardware acceleration - see https://immich.app/docs/features/ml-hardware-acceleration
    #   file: hwaccel.ml.yml
    #   service: cpu # set to one of [armnn, cuda, openvino, openvino-wsl] for accelerated inference - use the `-wsl` version for WSL2 where applicable
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9@sha256:4963247afc4cd33c7d3b2d2816b9f7f8eeebab148d29056c2ca4d7cbc966f2d9
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

  database:
    container_name: immich_postgres
    # image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    image: ghcr.io/immich-app/postgres:18-vectorchord0.5.3-pgvector0.8.1
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - pgdata:/var/lib/postgresql
    restart: always

volumes:
  pgdata:
  model-cache:
```

 [ Previous Post](https://willifix.net/blog/update-docker-grav-from-version-1-to-2) [Next Post ](https://willifix.net/blog/howto-toggle-showhide-crow-translate-in-swaywm)

---

## Navigation

- Parent: [Blog](https://willifix.net/blog.md)
- Previous: [howto toggle (show/hide) crow-translate in swaywm](https://willifix.net/blog/howto-toggle-showhide-crow-translate-in-swaywm.md)
- Next: [update docker-grav from version 1 to 2](https://willifix.net/blog/update-docker-grav-from-version-1-to-2.md)