Skip to main content

Python installation details

Extras​

ExtraWhat it adds
editorialONNX Runtime and Hugging Face Hub, for the context heads and the two detectors. The one you need
editorial-cudaThe same on a CUDA host. Replaces editorial, never joins it
macThe pyobjc Metal binding, so the automatic tier sees the GPU. Not enough to cut with alone
musicThe bundled royalty-free track library
authOIDC login (authlib)
demucsLocal Demucs stem separation for music ducking (Torch, about 80 MB of model)
alleditorial, music, auth and demucs (no demucs on Linux ARM64, where it has no wheel)
all-macall 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.