Skip to main content

Quick start

Run Immich Memories beside your existing Immich server, then make a short film from one album. Start with Basic if you are unsure. It makes a complete film on a CPU. Choose GPU if you have an NVIDIA GPU and want picture descriptions, and Full if you also run a text reader. You can switch tiers later.

TierWhat you getWhat you need
BasicA complete film with titles and bundled music, up to 1080p2 CPU cores, 4 GiB RAM for the app
GPUBasic plus picture descriptions and extra selection and sharing checksNVIDIA GPU, driver and Container Toolkit; room for the app and model services
FullGPU plus a text reader that refines the draftThe GPU setup and a reader server with a 32k context window

All three need Docker Compose v2, an Immich library and an API key, on Immich 2.7.5 or later (v2) or 3.2.4 or later (v3). Older v3 releases have security holes Immich has since fixed. Allow about 25 GB for app data plus 0.35 GB per 1,000 pictures and videos, plus the images, model caches and finished films. GPU and Full give the app an 8 GiB limit, and the model services need memory on top. Check the tier requirements if you are choosing hardware.

Other platforms: Synology Container Manager, with screenshots, Unraid, TrueNAS and Portainer, native Mac or Linux, Kubernetes. Apple Silicon uses the native install for GPU and Full. For a NAS with a separate GPU machine, use the setup builder and its GPU box option.

1. Download the files​

Choose the tab for your tier. Run its commands in a new folder, separate from your Immich install. The files match the release shown on this docs site.

Download Basic installation files (v1.0.0)
mkdir -p immich-memories && cd immich-memories
curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v1.0.0/docker-compose.yml"
curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v1.0.0/example.env"
cp example.env .env
sed -i.bak 's/^IMMICH_MEMORIES_VERSION=.*/IMMICH_MEMORIES_VERSION=1.0.0/' .env && rm .env.bak

This starts one app container. No GPU or separate model server is needed.

Prefer filled-in files or a stack editor? Use the setup builder.

2. Connect Immich​

In Immich, open Account Settings → API Keys → New API Key. Leave All unchecked and select these ten read permissions:

user.read, asset.read, asset.statistics, asset.view, asset.download, face.read, person.read, person.statistics, album.read and map.search.

For a larger library, optional tag.read finds previously generated films through the tag index instead of checking video tags individually. The API-key guide lists the other optional read and upload permissions.

Copy the key. Open .env and fill in:

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

Use an Immich address the container can reach. localhost means the container itself. Set TZ to your timezone. Upload permissions can wait until you want to send films back.

Create the folder for finished films, give the app permission to write there and protect .env:

mkdir -p output
sudo chown 1000:1000 output
chmod 600 .env

Keep .env with your backups. On Synology, use the folder permission recipe in place of chown.

Open the app from another computer​

The app asks for a sign-in. With nothing configured, the first start generates a password (step 4 says where to read it). This is the Immich Memories login, separate from your Immich account.

For access from another computer on your trusted LAN, also set this in .env before starting:

UI_BIND_ADDRESS=0.0.0.0

To choose your own login instead of the generated one, add these two lines as well, with a password of at least 12 characters:

IMMICH_MEMORIES_AUTH_USERNAME=admin
IMMICH_MEMORIES_AUTH_PASSWORD=replace-with-your-own-long-password

This setup uses HTTP on your trusted LAN. On your own desktop, keep the default localhost binding.

3. Start the app​

docker compose up -d

The first start pulls the container images. GPU and Full also wait for the caption weights and the service health checks before starting the app, so let the command finish. Later starts reuse the downloaded files.

4. Open the app and download models​

  • On this computer: open http://localhost:22830.
  • From another computer: open http://your-server-address:22830, using the Docker host's LAN address.

Sign in. If you set no login of your own, the username is admin and the generated password is in the container log: run docker compose logs immich-memories and look for the line with the username and password. Write it down: later starts do not print it again. Lost it? See the generated password.

Open Memory. In the Download models card, review the files and press Download models. The card disappears when the required files are ready. They download once and stay in the app's data volume; if they are already there, there is no card.

First visit on Basic: the Download models card lists the DINOv2 export, the WordNet corpus and the music library, with their sizes, hosts and checksums, and downloads nothing until you press the buttonFirst visit on Basic: the Download models card lists the DINOv2 export, the WordNet corpus and the music library, with their sizes, hosts and checksums, and downloads nothing until you press the button

Basic is shown above. GPU and Full list more files.

GPU and Full: check the model services​

The app's download card covers its local model files. GPU and Full also run model services, which can still be downloading weights. Before the first film, check those services from the installation folder:

docker compose exec -T immich-memories immich-memories preflight

Continue when Immich, required models and output checks pass, along with GPU inference, captions and the Laya family-viewing check. Full also needs the reader check to pass. Follow the fix beside any failed check. Read preflight results if you are unsure.

Make your first film​

Choose an album of 20–50 pictures, review the cut, then render. Your first film walks through it on Basic, GPU and Full.

Prefer the terminal for model downloads? See Download models from the CLI.

If it stops​

Installation help covers connection errors, missing models, ports, permissions and Docker networking. Tested deployments records which versions and platforms have been exercised.