Python installation details
Extras
| Extra | What it adds |
|---|---|
editorial | ONNX Runtime and Hugging Face Hub, for the context heads and the two detectors. The one you need |
editorial-cuda | The same on a CUDA host. Replaces editorial, never joins it |
mac | The pyobjc Metal binding, so the automatic tier sees the GPU. Not enough to cut with alone |
music | The bundled royalty-free track library |
auth | OIDC login (authlib) |
demucs | Local Demucs stem separation for music ducking (Torch, about 80 MB of model) |
all | editorial, music, auth and demucs (no demucs on Linux ARM64, where it has no wheel) |
all-mac | all plus mac |
Never install editorial and editorial-cuda together: onnxruntime and onnxruntime-gpu own
the same import name, and the one that answers is whichever pip wrote last.
GPU title rendering needs no extra: its kernel library is a base dependency wherever it publishes a
wheel (Title kernels). Local ACE-Step music on a Mac is a checkout
job (make install-acestep, then make check-local-audio): Generated music.
exiftool is worth having on an Apple HEIC library: it is the fallback when the Python HDR headroom
parser trips on an unusual file. brew install exiftool, or apt install libimage-exiftool-perl.
From a checkout
git clone https://github.com/sam-dumont/immich-memories.git
cd immich-memories
uv sync --extra editorial # or --extra all-mac on Apple Silicon
make web-client # the web UI, built from web/; needs Node 22
uv run immich-memories ui
uv sync installs into the clone's .venv and puts nothing on your PATH: inside the clone it is
always uv run immich-memories .... pip install -e ".[editorial]" works too. A checkout is the only install
that needs Node: the PyPI wheel and the Docker image ship the web client already built. Skip
make web-client and the CLI still works, but /app only tells you to build the client.
Installation troubleshooting
Package, Python and FFmpeg
Any FFmpeg build with the zscale filter works. On a Mac, start with Homebrew's plain package:
brew install uv ffmpeg
ffmpeg -hide_banner -filters | grep zscale
If that prints a zscale line, keep this FFmpeg. If it prints nothing, install the fuller build:
brew install ffmpeg-full
export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"
ffmpeg -hide_banner -filters | grep zscale
Keep that PATH entry in ~/.zprofile if you need ffmpeg-full. A command run over SSH does not
read that file unless you start a login shell, for example
ssh host "zsh -l -c 'immich-memories preflight'". Check zscale in the shell that will run the app.
On Debian/Ubuntu, install FFmpeg with sudo apt install ffmpeg and run the same filter check.
Use the versioned package command from Native installation.
The command pins --python 3.12 on purpose. The package runs on Python 3.11, 3.12 and 3.13: the
GPU title renderer (quadrants) ships no 3.14 wheel, so 3.14 is refused. uv tool install finds or
downloads a compatible interpreter on its own; the pin just makes it the same one everywhere. With
pip, create the virtual environment from Python 3.11, 3.12 or 3.13; pip on 3.14 refuses the package.
That command pins the release's PyPI version, with no checkout or local wheel build. With pip, use the same pinned package specification inside the app's virtual environment.
A bare install lacks the ONNX runtime needed for picture classifiers and for the speech detector (FireRedVAD, bundled in the package). Without it, a video's cut is still chosen from its picture and its loudness, but may start or end mid-sentence. The same model also detects a clip's own music or singing; without the ONNX runtime, the soundtrack never steps aside for it.
The command above includes --with "laya-mlx>=0.2,<0.6" on Apple Silicon. Only GPU and Full use it: on Basic
you can drop that part. For GPU or Full, keep it (or append --with "laya-mlx>=0.2,<0.6" to the versioned
uv tool install command). all-mac supplies the Metal bindings but does not include this audience-classifier
runtime. With pip, install "laya-mlx>=0.2,<0.6" using the same virtual environment as the app. Downloading
its checkpoint with models fetch does not install the Python runtime. See the
Mac recipe for checkout commands.
pi-heif, the HEIC decoder, is a base dependency. If an existing installation cannot import it,
reinstall or sync the selected application version with the same extras before testing another
film. An old environment with new source files is not an updated install.
uv tool install puts the command in ~/.local/bin. If it warns that this folder is not on your
PATH, run uv tool update-shell and open a new terminal. The terminal you ran it in still
cannot find immich-memories: add it for the current shell with
export PATH="$HOME/.local/bin:$PATH". Do the same in a non-login SSH shell. If you run with a
different home directory, use the installed command's absolute path; changing the home does not
move the uv installation.
Then continue with Connect Immich and choose the tier in the native installation guide.
Daily automation
A laptop's UI is rarely running all day. Install a system schedule:
immich-memories auto install --hour 9
Run the printed Activate: command once. The installer uses launchd on macOS, a systemd user
timer on Linux, or a cron command otherwise. On headless Linux, run loginctl enable-linger "$USER". Run Deactivate: before auto install --uninstall: it removes files without stopping a loaded schedule. For systemd, run systemctl --user daemon-reload after removal; for cron, remove the pasted entry.
Keep credentials in config.yaml: scheduled jobs do not inherit your interactive shell.
On macOS, a missed run happens after wake; launchd does not wake the machine.
macOS and an Immich on your network
macOS blocks a program from reaching other machines on your local network until you allow it, and your NAS is one of them. curl and the browser are exempt, which makes this confusing: curl reaches Immich while a scheduled immich-memories gets No route to host (errno 65). The permission belongs to the interpreter the job runs, the Python in your virtual environment or uv's managed python3.12 (something like ~/.local/share/uv/python/cpython-3.12.x-macos-aarch64-none/bin/python3.12), not to Terminal. Allowing Terminal, or running a command there, grants nothing to the 09:00 job.
immich-memories auto install checks this for you when your Immich is on a private address. It starts a temporary LaunchAgent that runs the same launcher the schedule runs, with config test (it only pings Immich), waits up to 20 seconds, removes the agent, and prints a pass or a fail. If macOS asks whether Python may find devices on your local network, click Allow, then run auto install again. Run the check while you are at the Mac so you can answer. A failed check can also mean a wrong config, an invalid key or an unreachable server: check immich-memories config test before changing permissions. For a Local Network denial without a prompt, check the interpreter in System Settings > Privacy & Security > Local Network. An Immich on the internet or on localhost is never blocked, so nothing is checked.
If the check failed and you have not run Activate, remove the pending installation with
immich-memories auto install --uninstall alone. There is no loaded schedule to deactivate.
A Python upgrade can change the interpreter identity and require another Local Network approval. immich-memories auto status says when the interpreter is no longer the one that was checked: run auto install again at the Mac.