Skip to main content

Can I run this?

Start with Basic, one prebuilt Docker container. Budget two CPU cores, 4 GiB for the app on top of Immich's own needs, and about 25 GB of app data plus 0.35 GB per 1,000 pictures, plus images and output. GPU and Full need additional services. Hardware encoding alone does not turn on GPU; a text reader alone does not turn on Full.

Status meanings​

StatusMeaning
Verified candidateAn unpublished candidate made playable films; the transcript records supplied artifacts, fresh installation or warm upgrade, and remaining checks
Verified upgradeAn existing installation was upgraded with public release artifacts and made a playable film; setup corrections are disclosed
Verified first runA tester installed from scratch with public artifacts and docs, got a playable film, and the transcript is linked
PartialA narrower check passed: a warm benchmark, a developer-run install, or preflight without a full film
Documented, untestedThe steps exist and should work, but nobody has run them end to end yet
UnsupportedNo supported route for this combination; the reason and the alternative are stated

The matrix​

Keyed by release and hardware. When a newer release is tested on the same hardware, the row updates in place rather than piling up history.

PlatformInstall methodRelease verifiedHardwareTier reachedStatusNotes
Linux x86-64Basic Composev1.0.0-rc.8 candidateIntel Xeon E3-1240 v6, Docker-in-Docker, 4 GiB app limitBasicVerified candidateFresh app volume, supplied image archive; album and month films, software H.264; recovered from a 15-second connection outage; transcript
SynologySSH + Composev1.0.0-rc.8 candidateDS423+, Intel J4125, 4 GiB app limit, software H.264BasicVerified candidateFresh app volume, supplied image archive; authenticated UI album and CLI month films; restart and download checks; transcript
SynologyContainer Manager GUIn/aany Synology, software encodingBasicDocumented, untestedProject and folder dialogs inspected; creating and starting the app through the GUI is untested
UnraidGUI templaten/aany x86-64, software encodingBasicDocumented, untestedReport your results
TrueNASCustom appn/aany x86-64, software encodingBasicDocumented, untestedReport your results
Linux ARM64Composen/aARM64, software encodingBasicDocumented, untestedGPU overlays need CUDA and don't apply here
Apple SiliconDocker Desktopv0.103.0M-series, software H.264BasicPartialIsolated runtime, not a public-image pull
Apple SiliconNative uv/pipv1.0.0-rc.8 candidateM5 Max, 128 GB; M2 Pro, 16 GB; VideoToolboxBasicVerified candidateSupplied wheel, warm upgrades of isolated installs; album and month films on both Macs; transcript
Kubernetes (RKE2)Generated manifests, GPUv1.0.0-rc.8 candidateNVIDIA T1000 8 GB, shared GPUGPUVerified candidateFresh namespace, app and inference images pinned by digest; GPU inference, NVENC, CUDA titles; album and month films; transcript
KubernetesIndependently managed servicesv1.0.0-rc.8NVIDIA T1000 8 GBFullVerified upgradePublished app and CUDA images pinned by digest; automatic film, upload and public delivery link checked. Custom probes needed the dedicated health endpoints
NAS appStandalone Docker GPU workern/an/aGPUDocumented, untestedKubernetes worker route is verified; Docker worker is not
NAS appKubernetes GPU workerv0.103.0NVIDIA T1000 8 GBGPUPartialWorker routing needed a fix before the film completed
BasicPrepared models, blocked internetv0.103.0Docker and KubernetesBasicPartialIsolated runtime and full decode passed; release-download path not separately checked
BasicPlus a local text modeln/an/aBasic + textDocumented, untestedModel conformance checked separately; a full offline film with it is not

The candidate rows cover unpublished artifacts built for acceptance. They do not claim a public release download or a cold install where a warm upgrade was used. The published-artifact first runs were on v1.0.0-rc.7.

A verified first run covers installation and a playable film through that route. Separate features, such as the native macOS scheduler, have their own checks in the linked transcript. Older partial rows below a verified route describe different setups, not a lower status for the tested route.

What each route needs​

RouteInfrastructure and budgetsReader
Basic Compose or vendor GUIDocker/Compose or a vendor manager, 2 cores, 4 GiB app, 25 GB + 0.35 GB per 1,000 pictures of app data, plus image/outputNone required by default; Immich access only
Generated Kubernetes GPUCluster with NVIDIA device access, a storage class and configured GPU sharing: inference reserves one allocation; captions share the device without a reservation. App: 8 GiB/4 CPUs plus service budgetsExternal reader for Full
Independent KubernetesOperator-supplied model/worker endpoints and their own RAM/VRAM/storageExternal reader; operator controls GPU sharing and egress
Native Apple SiliconPython, FFmpeg, app/model memoryApp-owned llama-server, or an external server
NAS + GPU boxNAS app budget plus a separate worker/model hostInference/caption traffic to that host; rendering only moves there if a render endpoint is configured
Offline Basic, or extra local modelsModels prepared first, firewall covering every process that needs itNone by default; the local-model recipe adds its own text server

Immich version support​

The client implements the Immich v2 and v3 API contracts and detects the major version from /api/server/version. Leave api_version: auto; forcing v2 or v3 is a troubleshooting override, not a way to make an unsupported server supported.

The real-server CI gate runs Immich 2.7.5, 3.2.4 and 3.3.3. Run at least 2.7.5 on v2 and 3.2.4 on v3: earlier v3 releases carry fixed security problems (an SVG upload that reaches ImageMagick before 3.2.4, broken access control on an admin endpoint before 3.0.4). Other versions may work when their API major matches; run the checks below before relying on them. Native person sharing has its own version checks.

immich-memories config test
immich-memories preflight

In Docker, prefix these with docker compose exec -T immich-memories. config test reports the server version and whether your key can read; it doesn't upload anything. Use the minimum read permissions for a new key, and add upload/delete only for the delivery features you've turned on.

Reporting a result​

If you've run a platform or method marked "Documented, untested" above, open an issue with your release, hardware, and whether the film completed. Detailed provenance (exact image digests, timings, intermediate failures) goes in that issue, not on this page: the table only needs to say what's verified and on what.