This document describes the build system and tooling infrastructure used across the Immich codebase. It covers multi-stage Docker builds, platform-specific ML builds, and production image optimization using pnpm, uv, and mise.
Immich uses a monorepo architecture with pnpm workspaces for TypeScript/JavaScript packages and specialized build systems for mobile (Flutter) and machine learning (Python).
The project uses pnpm 10.33.4+ as specified in package.json10:
The build system leverages workspace filtering to manage dependencies across the following primary components:
immich (Server)immich-web (Web)@immich/cli (CLI)@immich/sdk (TypeScript SDK)@immich/plugin-sdk & @immich/plugin-core (Plugins)Sources: package.json1-13 pnpm-lock.yaml1-17 mise.toml57-58
Sources: server/Dockerfile15-17 server/Dockerfile23-24 server/Dockerfile40-41 server/Dockerfile51-52 mise.toml57-58
Immich utilizes a multi-stage Docker build process to optimize production image size and security. The primary build logic is contained in server/Dockerfile1-122
The build process is divided into functional stages that parallelize the compilation of different monorepo components.
Stage Details:
corepack and pnpm on top of a development base image server/Dockerfile1-10--filter immich and performs a pnpm deploy to /output/server-pruned to isolate production dependencies server/Dockerfile12-24i18n/ directory and outputs to /usr/src/app/web/build server/Dockerfile26-41@immich/cli package and its dependency @immich/sdk server/Dockerfile43-53mise to install specialized toolchains (like Binaryen and Extism) to compile WASM-based plugins server/Dockerfile55-81Sources: server/Dockerfile1-122 mise.toml25-27
The final stage server/Dockerfile83-119 constructs the runtime environment:
libmimalloc.so.3 via LD_PRELOAD for memory allocation efficiency server/bin/start.sh18-23NVIDIA_DRIVER_CAPABILITIES and NVIDIA_VISIBLE_DEVICES for hardware acceleration server/Dockerfile87-88immich-healthcheck binary server/Dockerfile121Sources: server/Dockerfile83-121 server/bin/start.sh18-23
The machine learning service machine-learning/Dockerfile1-167 uses a dynamic build system to support various hardware backends.
The build is controlled by the DEVICE argument, which selects different base images and dependency sets machine-learning/Dockerfile1-27
| Backend | Base Image / Toolchain | Target Hardware |
|---|---|---|
| cpu | python:3.11-bookworm | Standard x86/ARM CPUs |
| cuda | nvidia/cuda:12.2.2-runtime | NVIDIA GPUs |
| openvino | python:3.13-slim-trixie | Intel GPUs/CPUs |
| armnn | ARMNN_VERSION="v24.05" | ARM Mali GPUs |
| rknn | RKNN_TOOLKIT_VERSION="v2.3.0" | Rockchip NPUs |
| rocm | rocm/dev-ubuntu-24.04 | AMD GPUs |
Sources: machine-learning/Dockerfile1-117 docs/docs/features/ml-hardware-acceleration.md10-17
The ML service uses uv for high-performance Python dependency resolution machine-learning/Dockerfile36-40
uv sync installs dependencies based on the uv.lock file and the selected hardware extra machine-learning/Dockerfile40Sources: machine-learning/Dockerfile36-40 machine-learning/uv.lock1-14
Immich uses mise as a unified task runner and tool manager to ensure consistency between local development and CI/Docker builds.
The mise.toml file defines cross-platform tasks for common operations mise.toml1-179:
| Task | Command | Purpose |
|---|---|---|
plugins | pnpm --filter ... build | Compiles WASM plugin packages mise.toml55-59 |
open-api | Multiple sub-tasks | Generates TS and Dart SDKs from server spec mise.toml72-81 |
dev | docker compose ... up | Starts development environment mise.toml88-93 |
clean | find ... -rm -rf | Removes build artifacts and node_modules mise.toml169-178 |
Sources: mise.toml55-179 server/Dockerfile81
Mise pins specific versions of critical build tools to prevent environment drift mise.toml17-49:
24.15.0 mise.toml1810.33.4 mise.toml203.44.0 mise.toml197.1.3-6 (Jellyfin portable build) mise.toml41-42Sources: mise.toml17-49 package.json10
The build system facilitates hardware acceleration for both ML and Transcoding by preparing specific drivers and libraries.
The immich-server image includes jellyfin-ffmpeg and sets LD_LIBRARY_PATH to include its libraries server/bin/start.sh24 It supports several APIs:
Sources: server/bin/start.sh24 docs/docs/features/hardware-transcoding.md11-57 docker/hwaccel.transcoding.yml1-10
The immich-machine-learning image includes backend-specific libraries:
.deb packages machine-learning/Dockerfile49-62libcudnn9-cuda-12 machine-learning/Dockerfile71librknnrt.so for Rockchip NPUs machine-learning/Dockerfile115Sources: machine-learning/Dockerfile49-115 docs/docs/features/ml-hardware-acceleration.md28-87
Refresh this wiki