rtp4jc/immich-animals sidecar-v0.1.0

animal-ml sidecar v0.1.0 (beta)

on GitHub

First beta of the animal-ml sidecar to add your dogs to Immich's People tab.

Immich already detects human faces and groups them into people. This runs alongside it and does the same for individual dogs.

This beta is about dogs. Cats and other animals are not supported yet. A cat is occasionally detected, but that is not a goal of this release.

Before you start

Use Refresh on the Face Detection queue, not Reset. Refresh keeps every face already in your library, so names, merges and hidden people survive both adding the sidecar and removing it. Reset deletes all named faces and manual merges.

Setup

Next to your Immich docker-compose.yml, create docker-compose.override.yml:

services:
  animal-ml:
    container_name: animal_ml
    image: ghcr.io/rtp4jc/animal-ml:0.1.0
    environment:
      UPSTREAM_ML_URL: http://immich-machine-learning:3003
    restart: always

docker compose up -d animal-ml

Then Administration → Settings → Machine Learning → set the URL to http://animal-ml:3003. Leave Min Detection Score and Max Distance alone as the sidecar uses its own values for dogs.

Finally Administration → Job Queues → Face Detection → Refresh (this will take a long time if you have a large library)

Full instructions: sidecar/README.md

What to expect

Dogs you photograph a lot cluster well; a dog with 673 photos put 491 of them in one person. A dog with 11 photos scattered across five.

• Dogs with under ~15 photos may not group at all
• Similar-looking dogs get mixed together
• About one cat photo in seven is detected as a person
• Photos of people, landscapes, horses and buildings produce no false positives

Measured on a held-out set of 121 individual dogs (1524 photos) plus 450 dog-free photos: 80% of in-the-wild dog photos produce a detection. Verified end-to-end against a stock Immich v3.2.2 stack.

How

This runs as a docker container next to the other Immich docker containers. It intercepts requests to detect people, detects dogs and produces an identity embedding, calls the actual Immich ML docker container and merges the results containing people and dog detections for each image.

Assets

The model files are attached here and baked into the published image. Verify them with sha256sum -c SHA256SUMS.

Licence

AGPL-3.0, because the detector is fine-tuned from Ultralytics YOLO11. The models are trained on data whose terms permit non-commercial research and personal use only — see NOTICE.