imagegenius/immich
Immich is a high performance self-hosted photo and video backup solution.
Supported Architectures
We use Docker manifest for cross-platform compatibility. More details can be found on Docker's website.
To obtain the appropriate image for your architecture, simply pull ghcr.io/imagegenius/immich:latest
. Alternatively, you can also obtain specific architecture images by using tags.
This image supports the following architectures:
Architecture | Available | Tag |
---|---|---|
x86-64 | ✅ | amd64-<version tag> |
arm64 | ✅ | arm64v8-<version tag> |
armhf | ❌ |
Version Tags
This image offers different versions via tags. Be cautious when using unstable or development tags, and read their descriptions carefully.
Tag | Available | Description |
---|---|---|
latest | ✅ | Latest Immich release with an Ubuntu base. |
noml | ✅ | Latest Immich release with an Ubuntu base. Machine-learning is completely removed, making it still compatible with hardware accelaration. |
alpine | ✅ | Latest Immich release with an Alpine base. Machine-learning is completely removed, making it a very lightweight image (can have issues with RAW images). |
Application Setup
The WebUI can be accessed at http://your-ip:8080
Follow the wizard to set up Immich.
To use Immich, you need to have PostgreSQL 14/15/16 server with pgvecto.rs set up externally, and Redis set up externally or within the container using a docker mod.
To set up redis using the docker mod, use the following:
Set DOCKER_MODS=imagegenius/mods:universal-redis
, and REDIS_HOSTNAME
to localhost
.
To use a SSL connection to your PostgreSQL database, include a PostgreSQL URL in the DB_URL
environment variable.
Hardware Acceleration
Intel Hardware Acceleration
To use Intel Quicksync hardware acceleration:
-
Ensure your container has access to the
/dev/dri
video device. -
Add the device to your container by including the following option in your Docker run command:
docker run --device=/dev/dri:/dev/dri ...
Nvidia Hardware Acceleration
For Nvidia GPUs with Nvidia/CUDA hardware acceleration:
-
First, install the Nvidia container runtime on your host machine. Follow the [installation instructions here](https://github.com/NVIDIA/ nvidia-docker).
-
After installing
nvidia-docker2
, recreate or create a new Docker container using the Nvidia runtime. This can be done in two ways:-
Add both
--runtime=nvidia
andNVIDIA_VISIBLE_DEVICES=all
to your Docker run command. Replaceall
with a specific GPU's UUID if needed. Example:docker run --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all
-
Alternatively, use
--gpus=all
in your Docker run command. Example:docker run --gpus=all ...
-
Import your existing libraries into Immich
- Mount your existing library folder to
/import
- In your administration settings, include
/import
as the external path for your user (if you have multiple users with existing libraries set the external path to/import/<user>
) - In your account settings, add a new library and set the path to
/import
or/import/<user>
Usage
Example snippets to start creating a container:
Docker Compose
---
version: "2.1"
services:
immich:
image: ghcr.io/imagegenius/immich:latest
container_name: immich
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
- DB_HOSTNAME=192.168.1.x
- DB_USERNAME=postgres
- DB_PASSWORD=postgres
- DB_DATABASE_NAME=immich
- REDIS_HOSTNAME=192.168.1.x
- DB_PORT=5432 #optional
- REDIS_PORT=6379 #optional
- REDIS_PASSWORD= #optional
- MACHINE_LEARNING_WORKERS=1 #optional
- MACHINE_LEARNING_WORKER_TIMEOUT=120 #optional
volumes:
- path_to_appdata:/config
- path_to_photos:/photos
- path_to_imports:/import:ro #optional
ports:
- 8080:8080
restart: unless-stopped
# This container requires an external application to be run separately to be run separately.
# Redis:
redis:
image: redis
ports:
- 6379:6379
container_name: redis
# PostgreSQL 14:
postgres14:
image: tensorchord/pgvecto-rs:pg14-v0.1.11
ports:
- 5432:5432
container_name: postgres14
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: immich
volumes:
- path_to_postgres:/var/lib/postgresql/data
Click here for more info)
Docker CLI (docker run -d \
--name=immich \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Etc/UTC \
-e DB_HOSTNAME=192.168.1.x \
-e DB_USERNAME=postgres \
-e DB_PASSWORD=postgres \
-e DB_DATABASE_NAME=immich \
-e REDIS_HOSTNAME=192.168.1.x \
-e DB_PORT=5432 `#optional` \
-e REDIS_PORT=6379 `#optional` \
-e REDIS_PASSWORD= `#optional` \
-e MACHINE_LEARNING_WORKERS=1 `#optional` \
-e MACHINE_LEARNING_WORKER_TIMEOUT=120 `#optional` \
-p 8080:8080 \
-v path_to_appdata:/config \
-v path_to_photos:/photos \
-v path_to_imports:/import:ro `#optional` \
--restart unless-stopped \
ghcr.io/imagegenius/immich:latest
# This container requires an external application to be run separately.
# Redis:
docker run -d \
--name=redis \
-p 6379:6379 \
redis
# PostgreSQL 14:
docker run -d \
--name=postgres14 \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=immich \
-v path_to_postgres:/var/lib/postgresql/data \
-p 5432:5432 \
tensorchord/pgvecto-rs:pg14-v0.1.11
Variables
To configure the container, pass variables at runtime using the format <external>:<internal>
. For instance, -p 8080:80
exposes port 80
inside the container, making it accessible outside the container via the host's IP on port 8080
.
Variable | Description |
---|---|
-p 8080 |
WebUI Port |
-e PUID=1000 |
UID for permissions - see below for explanation |
-e PGID=1000 |
GID for permissions - see below for explanation |
-e TZ=Etc/UTC |
Specify a timezone to use, see this list. |
-e DB_HOSTNAME=192.168.1.x |
PostgreSQL Host |
-e DB_USERNAME=postgres |
PostgreSQL Username |
-e DB_PASSWORD=postgres |
PostgreSQL Password |
-e DB_DATABASE_NAME=immich |
PostgreSQL Database Name |
-e REDIS_HOSTNAME=192.168.1.x |
Redis Hostname |
-e DB_PORT=5432 |
PostgreSQL Port |
-e REDIS_PORT=6379 |
Redis Port |
-e REDIS_PASSWORD= |
Redis password |
-e MACHINE_LEARNING_WORKERS=1 |
Machine learning workers |
-e MACHINE_LEARNING_WORKER_TIMEOUT=120 |
Machine learning worker timeout |
-v /config |
Contains machine learning models (~1.5GB with default models) |
-v /photos |
Contains all the photos uploaded to Immich |
-v /import:ro |
This folder will be periodically scanned, contents will be automatically imported into Immich |
Umask for running applications
All of our images allow overriding the default umask setting for services started within the containers using the optional -e UMASK=022 option. Note that umask works differently than chmod and subtracts permissions based on its value, not adding. For more information, please refer to the Wikipedia article on umask here.
User / Group Identifiers
To avoid permissions issues when using volumes (-v
flags) between the host OS and the container, you can specify the user (PUID
) and group (PGID
). Make sure that the volume directories on the host are owned by the same user you specify, and the issues will disappear.
Example: PUID=1000
and PGID=1000
. To find your PUID and PGID, run id user
.
$ id username
uid=1000(dockeruser) gid=1000(dockergroup) groups=1000(dockergroup)
Updating the Container
Most of our images are static, versioned, and require an image update and container recreation to update the app. We do not recommend or support updating apps inside the container. Check the Application Setup section for recommendations for the specific image.
Instructions for updating containers:
Via Docker Compose
- Update all images:
docker-compose pull
- or update a single image:
docker-compose pull immich
- or update a single image:
- Let compose update all containers as necessary:
docker-compose up -d
- or update a single container:
docker-compose up -d immich
- or update a single container:
- You can also remove the old dangling images:
docker image prune
Via Docker Run
- Update the image:
docker pull ghcr.io/imagegenius/immich:latest
- Stop the running container:
docker stop immich
- Delete the container:
docker rm immich
- Recreate a new container with the same docker run parameters as instructed above (if mapped correctly to a host folder, your
/config
folder and settings will be preserved) - You can also remove the old dangling images:
docker image prune
Versions
- 23.12.23: - move to using seperate immich baseimage
- 07.12.23: - rebase to ubuntu mantic
- 07.12.23: - remove typesense (no longer needed)
- 24.09.23: - house cleaning
- 24.09.23: - add vars for ml workers/timeout
- 29.07.23: - remove cuda acceleration for machine-learning
- 23.05.23: - rebase to ubuntu lunar and support cuda acceleration for machine-learning
- 22.05.23: - deprecate postgresql docker mod
- 18.05.23: - add support for facial recognition
- 07.05.23: - remove unused
JWT_SECRET
env - 13.04.23: - add variables to disable typesense and machine learning
- 10.04.23: - fix gunicorn
- 04.04.23: - use environment variables to set location of the photos folder
- 09.04.23: - Cache is downloaded to the host (/config/transformers)
- 01.04.23: - remove unused Immich environment variables
- 21.03.23: - Add service checks
- 05.03.23: - add typesense
- 27.02.23: - re-enable aarch64 with pre-release torch build
- 18.02.23: - use machine-learning with python
- 11.02.23: - use external app block
- 09.02.23: - Use Immich environment variables for immich services instead of hosts file
- 09.02.23: - execute CLI with the command immich
- 04.02.23: - shrink image
- 26.01.23: - add unraid migration to readme
- 26.01.23: - use find to apply chown to /app, excluding node_modules
- 26.01.23: - enable ci testing
- 24.01.23: - fix services starting prematurely, causing permission errors.
- 23.01.23: - add noml image to readme and add aarch64 image to readme, make github release stable
- 21.01.23: - BREAKING: Redis is removed. Update missing param_env_vars & opt_param_env_vars for redis & postgres
- 02.01.23: - Initial Release.