Cimmich · Install

Community Preview 18 · active testing

Install Cimmich beside Immich.

About fifteen minutes and five checked steps. Setup confirms the Immich version, creates Cimmich's own Docker project and database, then lets you preview the connection before importing anything into Cimmich.

Your original media and Immich database remain unchanged.

Download Preview 18 Release assets

RequiresImmich 3.1.0 exactly

Install tested onmacOS and Linux Docker hosts

WindowsNot yet tested

The whole path

Before you begin

Four things to have ready.

Immich 3.1.0 already running
Docker Desktop, OrbStack or Docker Engine with Compose v2
curl, openssl and either sha256sum or shasum
Your normal Immich sign-in

Testing status

Preview 18 is still being tested. The commands below are the tested macOS and Linux Docker path. Windows testing has not been completed yet.

Already runningImmichYour media and database

Read-only connection

Setup addsCimmichIts own project and database

Install

Five steps from download to your library.

Download the release and verify it

Download the Preview 18 application bundle and SHA256SUMS. Do not use GitHub's automatically generated Source code archives.

macOS or Linux bundle ZIP bundle SHA256SUMS

Verify before extracting:

macOS

shasum -a 256 --ignore-missing -c SHA256SUMS

Linux

sha256sum --ignore-missing -c SHA256SUMS

The bundle you downloaded must report OK. The missing alternative archive is ignored. Extract your bundle, open a terminal in that folder and confirm:

ls INSTALL.md compose.yaml tools/install.sh docker compose version

Check the machine without changing it

Start Docker, then run the preflight:

./tools/install.sh --check

It checks the platform, commands, ports, disk and existing Cimmich state. It creates no containers or configuration. A ready new machine ends with:

{"docker":"ready","installer":"ready","state":"unchanged"}

Run the installer

./tools/install.sh

Setup asks how Docker should reach Immich and whether Private viewing mode should use an extra local password. For Immich on the same computer, the default is usually:

http://host.docker.internal:2283

For Immich on another machine, use a Docker-reachable LAN or HTTPS address without /api, credentials or a query string.

Remote Immich

Plain HTTP carries the read-only API key and requested media unencrypted. Use it only on a network you trust; prefer a valid HTTPS address otherwise.

If Docker or the network interrupts the build, fix the reported problem and continue:

./tools/install.sh --resume ./tools/install.sh --status

Create the read-only Immich key

In Immich, open Account Settings → API Keys → New API Key. Name it Cimmich read-only and grant only:

current-user read
asset read and original-asset download
Face read
Person read

Keep the key on screen for the next step. It goes only into Cimmich's write-only Settings field, never into a shell command or .env file.

Connect and preview the library

Open http://127.0.0.1:3413 and sign in with your normal Immich account.
Open Cimmich Settings → Library connection.
Paste the dedicated key.
Confirm the Immich account, exact version, permissions and library counts.
Import only when the preview is what you expect.

No additional model is required to install Cimmich or begin organising the archive. Cimmich builds and runs the matcher. Optional face-analysis providers can add observations and embeddings; they are inputs to matching, not the matcher itself.

Installation complete

Cimmich is ready.

You are done when Cimmich shows the expected Immich account and version, reports the import complete, and the library count matches the preview.

Open Cimmich Review your first person