Native Mac or Linux
Run the app directly on your machine. Apple Silicon uses Metal for GPU and Full; Docker on a
Mac cannot use Metal. Linux can run Basic locally or use a separate NVIDIA inference service.
You need Python 3.11–3.13 and FFmpeg with the zscale filter.
Apple Silicon
Choose Basic, GPU or Full below and enter your Immich address. The builder provides the package command, configuration and service commands for that tier.
- Basic: the app and local classifiers, with no separate model server.
- GPU: the app uses Metal; the commands also start the local caption server and install Laya.
- Full: adds the app-owned local reader. Leave its URL blank for that default, or enter your existing reader's URL and served model name. Allow memory for it alongside the app and captions.
This page runs entirely in your browser. What you type here is never sent anywhere: no requests, no analytics, no tracking. The files are built on this page and stay on it until you copy or download them.
Setup files for docs build v1.0.0. The app image and release assets use this same version.
The builder does not ask for your Immich API key. The files hold the placeholder replace-with-your-immich-api-key: create a key with the ten required read permissions and paste it over the placeholder in your own editor. Add the five upload permissions only to send films back; asset.delete is optional. Avoid the All preset.
Platform coverage and tested installations
See the deployment matrix for exact release and platform coverage.
Not yet tested as an end-to-end generated installation on native Mac. Files are checked with Compose and the form is checked in a browser. Those checks do not run this installation. Earlier NAS, Mac and GPU Kubernetes checks are recorded in the measured results. Tried it? Report your platform, release and preflight result.
Nothing here contacts an Immich or model server.
Save these files for a fresh install. For an existing install, change service URLs in Settings. Preflight checks whether the requested tier is ready. After it passes, make your first film.
config.yamlPreview config.yaml
immich:
url: "http://192.168.1.10:2283"
api_key: replace-with-your-immich-api-key
tier: basic
advanced:
llm:
enabled: false
base_url: ""
api_key: ""
model: gemma-4-E4B-it-Q4_0
brew install uv ffmpeg
ffmpeg -hide_banner -filters | grep zscale
# No output? HDR conversion needs zscale: brew install ffmpeg-full, then put $(brew --prefix ffmpeg-full)/bin first on your PATH.
uv tool install --python 3.12 --prerelease if-necessary-or-explicit "immich-memories[all-mac]==1.0.0" --with "laya-mlx>=0.2,<0.6"
umask 077
mkdir -p ~/.immich-memories
# Save the generated config.yaml in ~/.immich-memories (after umask 077, so only you can read your API key).
# Put your Immich API key in ~/.immich-memories/config.yaml (replace "replace-with-your-immich-api-key"): https://sam-dumont.github.io/immich-memories/docs/run/docker#the-api-key
test -f ~/.immich-memories/secret-key || openssl rand -hex 32 > ~/.immich-memories/secret-key
export IMMICH_MEMORIES_SECRET_KEY="$(cat ~/.immich-memories/secret-key)"
immich-memories config move-to-db tier llm.enabled llm.base_url llm.model llm.api_key
# move-to-db keeps the full file as config.yaml.bak, API key included. Once the app runs, delete it:
# rm ~/.immich-memories/config.yaml.bak
immich-memories models fetch
immich-memories preflight
immich-memories capabilities
immich-memories ui --host 127.0.0.1 --port 8080
Save the generated config at the path shown in the commands, replace the API-key placeholder with your scoped Immich key, then run the remaining commands. When preflight passes, open the localhost URL and make your first film. Keep the terminal running while using the app.
Linux or Intel Mac
1. Install the package
On Debian/Ubuntu, install FFmpeg with sudo apt install ffmpeg. On an Intel Mac:
brew install uv ffmpeg
Install uv if needed, then use the Linux / Intel Mac command below. It installs Python 3.12 and the packaged app:
# Linux / Intel Mac
uv tool install --python 3.12 --prerelease if-necessary-or-explicit "immich-memories[all]==1.0.0"
# Apple Silicon: use this instead
uv tool install --python 3.12 --prerelease if-necessary-or-explicit "immich-memories[all-mac]==1.0.0" --with "laya-mlx>=0.2,<0.6"
2. Connect Immich and choose the tier
Create ~/.immich-memories/config.yaml:
mkdir -p ~/.immich-memories
tier: basic
immich:
url: http://192.168.1.10:2283
api_key: your-api-key
Use the ten read permissions and keep the file private with
chmod 600 ~/.immich-memories/config.yaml.
For GPU, first start the NVIDIA inference and caption worker.
Set tier: gpu and add its endpoints:
advanced:
inference:
facts_base_url: http://192.168.1.50:8092
editorial:
preparation:
caption_base_url: http://192.168.1.50:8092/v1
Keep the worker on a trusted private network. The app also needs its Laya runtime and checkpoint;
models fetch prepares the checkpoint and preflight checks both.
For Full, set tier: full and add an enabled reader under the same
advanced section (keep the inference and caption entries above):
llm:
enabled: true
provider: openai-compatible
base_url: http://192.168.1.50:8000/v1
model: your-server-model-name
Use a server with 32k context and add api_key if required. Configure it before starting Full. A local reader needs llama-server on
PATH; an external reader needs its URL, served model and any API key.
3. Prepare and start
immich-memories models fetch
immich-memories preflight
immich-memories ui --host 127.0.0.1
Open http://localhost:8080 and make
your first film. Films default to ~/Videos/Memories.
Commands in other guides use a Docker prefix; here run immich-memories ... directly.
Access from another machine
Keep the localhost bind for a private desktop install; it still asks for the generated sign-in
(the password is printed once in the terminal).
immich-memories ui --host 0.0.0.0 opens it to the LAN, behind that sign-in. Set your own login with
authentication first if you want one. Network and security covers proxies and HTTPS.
After the first film
Set home and people, keep a backup, or enable automatic films. Upgrading preserves the installed extras and app data.
Installation details
Python installation details covers runtime extras, FFmpeg/PATH problems, pip, source checkouts and native scheduling. Installation help covers readiness failures. Tested deployments records platform coverage.
For a deliberate removal, use Stop, reset and uninstall.