# Python installation details

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/run/reference/python-install/>.

## 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](https://sam-dumont.github.io/immich-memories/docs/run/hardware.md#title-kernels)). Local ACE-Step music on a Mac is a checkout
job (`make install-acestep`, then `make check-local-audio`): [Generated music](https://sam-dumont.github.io/immich-memories/docs/better/music.md).

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

```bash
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:

```bash
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:

```bash
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](https://sam-dumont.github.io/immich-memories/docs/run/uv-pip.md).

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](https://sam-dumont.github.io/immich-memories/docs/run/reference/mac-example.md#install-the-app) 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](https://sam-dumont.github.io/immich-memories/docs/run/uv-pip.md#2-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:

```bash
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.
