uv or pip
For a Mac or Linux machine without Docker. You need Python 3.11 to 3.13 and FFmpeg on your PATH.
The Docker install is the other option.
Install
Any FFmpeg build with the zscale filter works: HDR conversion needs it. Homebrew's plain
ffmpeg 8.1 passed the check below. If yours does not, install ffmpeg-full and put it first
on your PATH:
brew install uv ffmpeg
brew install ffmpeg-full # only if grep zscale finds nothing
export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"
On Debian/Ubuntu, install FFmpeg with sudo apt install ffmpeg. Verify HDR support:
ffmpeg -hide_banner -filters | grep zscale
Install the package that matches this documentation build. Choose the command for your platform:
# Linux / Intel Mac
uv tool install --python 3.12 --prerelease if-necessary-or-explicit "immich-memories[all]==1.0.0rc1"
# Apple Silicon: use this instead
uv tool install --python 3.12 --prerelease if-necessary-or-explicit "immich-memories[all-mac]==1.0.0rc1" --with laya-mlx
The command pins --python 3.12 on purpose. The package supports Python 3.11 and newer, but the
GPU title renderer (quadrants) is only installed below 3.14. Without the pin, uv picks the
newest Python on your PATH (Homebrew's default is 3.14 now), the install succeeds, and titles
quietly fall back to PIL without SDF effects: preflight shows "Title rendering: WARNING PIL + FFmpeg".
If you already installed that way, reinstall with --force --python 3.12. With pip, create the
virtual environment from Python 3.11, 3.12 or 3.13.
Pre-tag rehearsals install a published wheel directly from their GitHub release; they are not uploaded to PyPI. RC/final commands pin the matching PyPI version. No source checkout or local wheel build is part of either route. A preview without published assets cannot supply this install. For 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.
For GPU or Full on Apple Silicon, append --with laya-mlx to the versioned uv tool install
command above. all-mac supplies the Metal bindings but does not include this audience-classifier
runtime. With pip, install laya-mlx 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.
Create ~/.immich-memories/config.yaml:
tier: basic
immich:
url: http://192.168.1.10:2283
api_key: your-api-key
The file holds the key, so keep it private: chmod 600 ~/.immich-memories/config.yaml. The app
warns at startup when other users can read it.
Create the key in Immich's Account Settings > API Keys with the ten read permissions. Add the upload set only if you send films back to Immich. Leave All unchecked. Then:
immich-memories models fetch
immich-memories preflight
immich-memories ui
Open http://localhost:8080 and make your first film.
Films default to ~/Videos/Memories. Set home coordinates for trips and public holidays:
Home and people.
Reaching the UI from another machine
Without authentication, the app binds to localhost. Enabling Basic auth or OIDC makes it listen beyond localhost. To keep an authenticated laptop install local, be explicit:
immich-memories ui --host 127.0.0.1
--host overrides the safety default, even with auth off. Enable login before exposing the UI.
For a proxy with HTTPS, use the proxy checklist.
Extras
For most installs, use all or all-mac. Smaller/custom installs:
| Extra | Adds |
|---|---|
editorial | CPU picture classifiers; the minimum for films |
editorial-cuda | CUDA classifiers on Linux; replaces editorial |
mac | Apple hardware bindings; not enough on its own |
music, audio | Bundled music and local-track metadata |
auth | OIDC login |
demucs | Local music stem separation |
Never install editorial and editorial-cuda together: both provide onnxruntime.
all includes editorial/music/audio/auth/demucs. all-mac includes the same except auth, plus mac.
On Linux aarch64, all and all-mac skip demucs: its sphn dependency ships no wheel there and
needs Rust plus a C compiler to build. Vocal separation shows unavailable instead of installing.
Local ACE-Step is a separate checkout setup, not a pip extra.
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.
If you run the UI as a permanent service, you can use its built-in daily timer instead.
Use one scheduler. Automate it covers both.
What to keep
Back up ~/.immich-memories/store.db with immich-memories store backup.
Keep the encryption key too if you save credentials in Settings.
Database and backups covers restore and PostgreSQL.
Logs, health and hardware
Logs go to stderr. Use immich-memories -v ... for debug output.
Diagnostics covers probes, preflight and log files.
Hardware encoding covers Apple, Intel/AMD and NVIDIA setups.
Add-ons
Point the app at the services you want: a reader, captions, inference, a render worker or generated music.
Updating
Use Upgrading. Keep the same extras when using pip.
From a checkout
For development, you also need Node 22 to build the web client:
git clone https://github.com/sam-dumont/immich-memories.git
cd immich-memories
uv sync --extra editorial
make web-client
uv run immich-memories models fetch
uv run immich-memories ui
On Apple Silicon, use --extra all-mac. Add --extra auth for OIDC.
Inside a checkout, use uv run immich-memories ...; it does not install a global command.
The published wheel and Docker image already contain the web client.
Stop or remove this installation
Stop, reset and uninstall separates retaining data for reinstall from deleting app state.