immich-ml
| Version | 2026.144.1443 |
| Repo | superproject |
Immich machine-learning backend serving face recognition and smart-search inference on port 3003.
Installs the uv Python package manager, then builds a dedicated
virtualenv at /opt/immich/machine-learning/.venv and installs the
immich_ml module from the pinned Immich source release. A supervised
immich-ml service runs python -m immich_ml, exposing the ML
inference API on port 3003 (its /ping endpoint answers “pong”) so the
Immich server can offload face detection and CLIP smart-search
embedding to this backend.
Services
Section titled “Services”immich-ml
Acceptance plan
Section titled “Acceptance plan”This candy’s plan: — the runnable spec charly check executes against a live deployment. check: steps are idempotent probes; run: steps change state.
| Intent | Step |
|---|---|
run |
download=https://astral.sh/uv/install.sh |
run |
command=curl -fL –retry 3 –retry-delay 2 “https://github.com/immich-app/immich/archive/refs/tags/${IMMICH_VERSION}.tar.gz” | tar xz -C /tmp mv /tmp/immich-$(echo ${IMMICH_VERSION} | sed ‘s/^v//’) /tmp/immich |
run |
command=uv venv /opt/immich/machine-learning/.venv cd /tmp/immich/machine-learning && VIRTUAL_ENV=/opt/immich/machine-learning/.venv uv pip install “.[cpu]” cp -r /tmp/immich/machine-learning/immich_ml /opt/immich/machine-learning/ rm -rf /tmp/immich |
run |
mkdir=${HOME}/.immich/models |
run |
mkdir=${HOME}/.cache/immich_ml |
check |
the dedicated machine-learning virtualenv ships a python interpreter |
check |
the immich_ml inference module is installed into the machine-learning tree |
check |
the uv package manager that built the venv is on the system PATH |
check |
the per-user model cache directory is provisioned under the home tree |
check |
the supervised immich-ml service is running |
check |
the ML inference API answers its health probe on port 3003 with pong |
check |
service=immich-ml |
check |
command=curl -fsS -o /dev/null -w “%{http_code}” http://127.0.0.1:3003/ping |