Skip to main content

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.

Choose a tier

Start with Basic if you are unsure. Every tier makes a complete film.

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.yaml
Preview 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

Install and check
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:

Install v1.0.0: choose your platform
# 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.