Quick start

Run Immich Memories beside your Immich server, then try a 30-second film from 20–50 photos/videos. No GPU or model server needed.

You need Docker with Compose v2, Immich v2 or v3, and two CPU cores, 4 GiB of RAM for this app in addition to Immich/host needs and 25 GB for its data, plus the image and finished films. Full requirements.

See tested deployments for exact platform evidence, Immich API versions and untested routes.

1. Download the files

Download the matching v1.0.0-rc.1 assets. Pre-tag rehearsals are marked -dev.N; release candidates are marked -rc.N.

Download installation files

mkdir -p immich-memories && cd immich-memories
curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v1.0.0-rc.1/docker-compose.yml"
curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v1.0.0-rc.1/example.env"
curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v1.0.0-rc.1/docker-compose.gpu.yml"
curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v1.0.0-rc.1/docker-compose.full.yml"
curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v1.0.0-rc.1/docker-compose.cuda.yml"
curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v1.0.0-rc.1/docker-compose.gpu-worker.yml"
curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v1.0.0-rc.1/docker-compose.postgres.yml"
cp example.env .env
printf '
IMMICH_MEMORIES_VERSION=1.0.0-rc.1
' >> .env
mkdir -p output

The base file runs Basic. GPU adds docker-compose.gpu.yml; Full also adds docker-compose.full.yml. NVIDIA adds docker-compose.cuda.yml. Set COMPOSE_FILE in .env to select those files. For filled-in files, use the setup builder.

Basic needs only docker-compose.yml and example.env (saved as .env). The other files are for GPU, Full, the render worker and PostgreSQL, so download them only if you take one of those routes.

Create output yourself, owned by uid 1000, so Docker does not make it as root. This is where local films land. Run it in the same folder, right after the downloads:

mkdir -p output && sudo chown 1000:1000 output   # drop sudo if you are root

The container runs as uid 1000. If you run mkdir as root and skip the chown, preflight fails with "Output directory is not writable". On Synology, chown is not enough: use the ACL recipe.

Already running another copy on this host? Give this one its own Compose project name, host port and container name, or the two share a volume:

echo 'COMPOSE_PROJECT_NAME=immich-memories-2' >> .env

Then in docker-compose.yml change container_name and the number before :8080 in the port line (keep ${UI_BIND_ADDRESS:-127.0.0.1}), for example ${UI_BIND_ADDRESS:-127.0.0.1}:8081:8080. Without a project name, a project in a folder called immich-memories reuses the first install's volume. Run every docker compose command below from this folder; the service name stays immich-memories.

2. Connect Immich

Open .env in a text editor and set:

IMMICH_URL=http://192.168.1.10:2283
IMMICH_API_KEY=your-api-key-here

Use the address the container can reach, usually your server's LAN address. localhost inside the container points at the container itself.

In Immich, create the key under Account Settings > API Keys > New API Key. Select the ten read permissions. Add the five upload permissions only if you want to send films back to Immich; leave All unchecked.

3. Start and download the local models

docker compose pull
docker compose up -d
docker compose exec immich-memories immich-memories models fetch
docker compose exec immich-memories immich-memories preflight

models fetch downloads the pinned local model and dictionary. Picture processing runs on your CPU. Preflight must pass Immich, required-model and output checks. Basic skips unconfigured optional services; a home-coordinate warning does not block an album film.

Over plain SSH with no terminal (a script, ssh host 'docker compose exec ...'), add -T: docker compose exec -T immich-memories immich-memories preflight.

Two more warnings are normal on a first run and do not block a film:

• Immich with a read-only key: upload permissions not granted, films stay local; asset.delete not granted, previous versions are kept. It only means the key cannot upload.
• Title rendering on a CPU without AVX (some Celerons): kernel backend crashed on this CPU: illegal instruction; titles fall back to the PIL renderer. Titles use the simpler renderer.

4. Open the app

On the machine running Docker, open http://localhost:8080.

For a headless NAS, run this on your desktop first, replacing the SSH account and server name:

ssh -L 8080:localhost:8080 you@your-nas

SSH login working does not mean forwarding is permitted. If the tunnel prints open failed: administratively prohibited, follow the Synology authenticated proxy route before exposing any LAN port. Do not change global SSH policy to make the tunnel work.

Then open the same localhost address on your desktop. The default port is available locally; authentication covers remote access.

Follow Your first film: create an Immich album with 20–50 supported photos/videos, choose Album, and set the length to 0.5 minutes. Review the cut and render with upload off. Shortening a film alone does not reduce how many inputs need preparation.

Cold setup includes the image pull, model download, input preparation and render. Hardware, input count and cache state matter. Measured numbers separate film generation from setup; larger periods can still take hours. The phase guide explains what progress and completion look like. After install covers home, people and backups. Got your first film? Choose your setup explains what more you can get.

If it stops

Message or symptom	Fix
Encoder: Pinned DINOv2 export missing	Run models fetch from step 3.
Output directory is not writable	On Linux, sudo chown -R 1000:1000 output. On Synology DSM, use the ACL recipe.
Immich: Connection failed	Check the URL and key in .env, then run docker compose up -d again.
The cut hangs on thumbnails while preflight is green	The host's network MTU is below Docker's. See the MTU fix.

Check the installation at any time:

docker compose exec immich-memories immich-memories preflight

For NAS-specific permissions and CPU settings: On a NAS. Without Docker: pip / uv.