Skip to main content

Apple Silicon with local services

Run natively to use the Mac's Metal GPU. This setup keeps the app, captions and text reader on one Mac; Immich can live elsewhere on your network. For a packaged install without local music generation, use the Python install.

Deployment explorerLocal services on Apple Silicon
Existing Immich server

Your Immich

Your photo and video library
Your Mac · native app

Immich Memories

Store · cache · output files
Same Mac · separate runtime

Caption server

1

Metadata + previewsPreparation starts with your library; originals remain in Immich.

2

Preview tiles + framesImages go to the caption service; the text reader is a separate role.

The app and caption runtime share one Mac. Captions and the reader are enabled in this recipe; generated music is optional. Select a service for details.

On a Mac it's one Python install and a launchd agent that runs it every day.

This path works on Apple Silicon with Metal and VideoToolbox; see measured examples for real numbers. That check didn't activate the reader or generate music; the Full and optional music steps below need their own configuration checks.

Install the app​

For a source checkout, install uv, ffmpeg-full, exiftool and Node 22 first. Use Python 3.12 if you plan to add local ACE-Step. From your release checkout:

brew install uv ffmpeg-full exiftool llama.cpp
export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"
ffmpeg -hide_banner -filters | grep zscale
git clone https://github.com/sam-dumont/immich-memories.git
cd immich-memories
git checkout YOUR_RELEASE_TAG
make dev
make dev-mac
uv pip install --python .venv/bin/python laya-mlx
uv run --no-sync python -c "import pi_heif, laya_mlx"

Replace YOUR_RELEASE_TAG with the release tag you intend to run. The Mac extras install the Metal bindings, but not laya-mlx. The extra install above supplies the audience classifier used by GPU and Full. pi-heif is already a base dependency for HEIC decoding. Keep the FFmpeg PATH export in your shell startup file and in the environment used to launch a service.

After changing checkout revisions, rerun make dev-mac and the laya-mlx install before starting the app. Copying source into an older environment does not update dependencies. The --no-sync commands below preserve that separately installed runtime; an explicit sync may require installing it again. Development setup covers source tools; the requirements page covers memory and supported platforms.

Set your Immich connection in Settings or a small config file. Keep the normal tier: auto setting. Start the local caption server in another terminal, using its pinned model and smolvlm2-500m-base-public alias. The llama.cpp recipe used less resident memory on the 16 GiB M2 smoke host. An existing mlxcel service is a separate process; stop it when replacing it, otherwise both models remain loaded. For an app on this same Mac, bind the caption server to 127.0.0.1.

Connect captions and the reader​

advanced:
  editorial:
    preparation:
      caption_base_url: http://localhost:8092/v1
  llm:
    enabled: true
    base_url: ""

The blank reader URL uses the app-owned local llama.cpp model. It starts when needed and releases its model before local music, stems and rendering. You do not need a second reader server. If you already use one, configure its URL and served model name using the reader guide.

Fetch the model files required by this configuration, then check it:

uv run --no-sync immich-memories models fetch
uv run --no-sync immich-memories preflight -v
uv run --no-sync immich-memories config show tier
uv run --no-sync immich-memories ui --host 127.0.0.1

Open http://localhost:8080 and make your first film. Automatic selection can use the native Metal preparation runtime; Full also needs the enabled reader, captions and Laya ready. Preflight names any missing requirement. A Docker container on a Mac cannot use Metal directly; this recipe runs outside Docker.

Optional local music​

Bundled or chosen music works without another model. To generate tracks locally, stop the app and install the separate audio environment in this checkout:

make install-acestep
make check-local-audio

Then add:

advanced:
  ace_step:
    enabled: true
    mode: lib
    model_variant: turbo
    use_lm: false

Restart the app. This smaller profile needs about 7 GB free for resident weights and 6 GB on disk; generation needs working memory too. Generated music and the audio runtime cover larger profiles, checks and fallback reporting. Each checkout or worktree needs its own audio installation.

Access from another machine​

Keep the explicit localhost app bind for a private desktop setup. To reach it from another machine, choose authentication and a network/proxy configuration first. Local caption routes have no built-in authentication; only broaden their bind address when another trusted app needs access.