Immich con Docker Compose: come installarlo e caricare le foto dal telefono

Immich è un archivio di foto e video che gira su un computer di casa. Si usa dal browser oppure con l’app per Android e iOS. Questa guida è per chi ha un PC o un piccolo server Linux e vuole installare Immich con Docker Compose, che il progetto indica come metodo consigliato per l’uso in produzione. Alla fine Immich risponde sulla rete di casa, esiste un utente amministratore e il telefono carica da solo le foto sul server. I comandi sono quelli della documentazione ufficiale di Immich, elencata in fondo. Si fa riferimento a Immich v3: il file .env lo indica di serie con IMMICH_VERSION=v3 e l’ultima release all’11 ottobre 2026 è la v3.3.1, uscita l’8 ottobre 2026.

Immich non sostituisce Google Foto in tutto e per tutto. Le foto restano in casa vostra, ma l’hardware, i dischi per le copie di sicurezza e il tempo per gestire il server sono a carico vostro. Nelle FAQ di Immich sono gli stessi sviluppatori a scrivere che probabilmente non si risparmia: per ospitare le foto in casa ci sono tanti buoni motivi, ma il risparmio raramente è uno di questi.

Cosa serve

I requisiti vengono dalla pagina Requirements:

• Sistema: Linux o un altro sistema *nix a 64 bit, per esempio Ubuntu o Debian. Immich gira su amd64 e arm64. Dalla v3, sui processori amd64 il container del machine learning richiede il livello di microarchitettura x86-64-v2, che la maggior parte delle CPU uscite più o meno dal 2012 in poi supporta.
• RAM: almeno 6 GB, consigliati 8 GB. Con soli 4 GB Immich può girare se si disattivano le funzioni di machine learning.
• CPU: almeno 2 core, consigliati 4.
• Disco: un file system compatibile con Unix che gestisca proprietari e permessi, come EXT4, ZFS o APFS. Miniature e video convertiti fanno crescere la libreria in media del 10-20%. Il database di solito occupa da 1 a 3 GB e dovrebbe stare su un SSD locale.
• Software: Docker con il plugin Compose. Su un server Linux si usa Docker Engine; Docker Desktop, la variante grafica, è sconsigliato su Linux. Il plugin Compose si installa insieme a entrambi seguendo le guide ufficiali di Docker.

Il comando giusto è docker compose, con lo spazio. Il vecchio docker-compose, con il trattino, è deprecato e Immich non lo supporta più.

Windows e macOS

Su Windows si può provare con Docker Desktop o con WSL 2, su macOS con Docker Desktop. La documentazione però lo sconsiglia con decisione: fuori da Linux Docker tende a funzionare male, e gli sviluppatori avvertono che su questi sistemi potranno aiutare molto poco nell’installazione e nella risoluzione dei problemi. Su Windows c’è anche un limite pratico: la cartella del database (DB_DATA_LOCATION) non funziona su dischi formattati NTFS o exFAT/FAT32, né in WSL se si usa una cartella di Windows montata, di solito sotto /mnt. Come aggirare il problema è spiegato più avanti, nella sezione sul file .env.

Immich funziona bene anche dentro una macchina virtuale completa, mentre Docker nei container LXC è sconsigliato.

Creare la cartella di Immich e scaricare i file ufficiali

Immich cambia spesso e alcune versioni introducono modifiche incompatibili con le precedenti. Per questo conviene scaricare il docker-compose.yml e il file delle variabili dall’ultima release, invece di copiarli da altre guide. Per prima cosa create la cartella che conterrà i due file:

mkdir ./immich-app

Poi entrate nella cartella:

cd ./immich-app

Scaricate il file di Compose dell’ultima release:

wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

Scaricate anche il file di esempio delle variabili, che viene salvato subito con il nome .env:

wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Se tutto è andato bene, nella cartella ci sono docker-compose.yml e .env. Il secondo inizia con un punto, quindi molti file manager lo nascondono. In alternativa potete scaricare i due file dal browser e spostarli nella cartella: in quel caso ricordatevi di rinominare example.env in .env.

Modificare il file .env

Aprite .env con un editor di testo. Il docker-compose.yml usa queste variabili per sapere dove salvare i dati e con quali credenziali. Ecco le righe da guardare (l’elenco completo è nella pagina Environment Variables):

• UPLOAD_LOCATION: la cartella in cui finiscono foto e video, di serie ./library. Indicate una cartella nuova su un disco con molto spazio libero.
• DB_DATA_LOCATION: la cartella del database PostgreSQL, di serie ./postgres. Dovrebbe stare su un SSD locale e mai su una condivisione di rete, di nessun tipo: per il database le condivisioni di rete non sono supportate.
• DB_PASSWORD: di serie vale postgres. Sostituitela con una password casuale fatta solo di lettere e numeri (A-Za-z0-9), senza spazi né caratteri speciali, così Docker non rischia di leggerla male. Il database non è esposto all’esterno, quindi la password serve solo per l’autenticazione locale. Per generarla si può usare l’utility pwgen.
• TZ: il fuso orario. Togliete il # all’inizio della riga e sostituite Etc/UTC con il vostro fuso, per esempio Europe/Rome. Immich lo usa quando non riesce a ricavare il fuso dai metadati di una foto, e anche per gli orari dei log e delle attività pianificate.
• IMMICH_VERSION: vale v3, cioè segue la versione principale 3. Le righe sotto il separatore (DB_USERNAME, DB_DATABASE_NAME) si possono lasciare come sono.

Su Windows o in WSL, se il disco scelto per il database non gestisce proprietari e permessi, la pagina Requirements suggerisce di usare un volume Docker al posto della cartella. Nel .env la riga diventa DB_DATA_LOCATION=pgdata. In fondo al docker-compose.yml, nella sezione volumes: che contiene già model-cache:, si aggiunge la riga pgdata:.

Avviare Immich con docker compose

Dalla cartella immich-app, che ora contiene i due file sistemati, avviate Immich come servizio in background:

docker compose up -d

Poi aprite nel browser di un computer della stessa rete l’indirizzo http://<IP-della-macchina>:2283. Al posto di <IP-della-macchina> mettete l’indirizzo IP locale del computer su cui gira Immich. La porta 2283 è quella predefinita del server. Se compare la pagina con il pulsante «Getting Started», l’installazione risponde. Se la pagina non risponde subito, aspettate e riprovate.

Applicare le modifiche al .env dopo il primo avvio

Se cambiate il file .env quando Immich è già in funzione, riavviare i container non basta: l’ambiente al loro interno resta quello vecchio finché i container non vengono ricreati. Di solito basta lanciare di nuovo lo stesso comando, perché Docker si accorge che il file è cambiato e ricrea i container interessati:

docker compose up -d

Se le modifiche non vengono applicate, forzate la ricreazione dei container:

docker compose up -d --force-recreate

Creare l’utente amministratore dall’interfaccia web

Il primo utente che si registra diventa amministratore e può poi aggiungere altri utenti. Aprite http://<IP-della-macchina>:2283, sostituendo <IP-della-macchina> con l’indirizzo IP locale del server come nella sezione precedente. Fate clic su «Getting Started» e seguite i passaggi per registrarvi e accedere. Come prova, caricate una foto dal browser: vi servirà anche per controllare l’app.

Installare l’app e attivare il caricamento automatico

L’app di Immich si scarica da:

• App Store, per iPhone e iPad;
• Google Play Store;
• FUTO F-Droid;
• GitHub Releases, come file APK;
• Obtainium, con il link di configurazione che trovate nella pagina Utilities del vostro server Immich.

Nell’app indicate come indirizzo del server http://<IP-della-macchina>:2283, cioè lo stesso indirizzo IP locale usato nel browser, e accedete con l’account appena creato. Se vedete la foto caricata dal browser, il collegamento funziona.

Per caricare le foto del telefono toccate l’icona della nuvola in alto a destra. Si apre la schermata di backup, dove scegliete gli album da inviare al server. Scorrete fino in fondo e toccate «Enable Backup»: l’app comincia a caricare tutti i file degli album scelti. Quanto ci vuole dipende da quante foto avete, e i caricamenti grandi possono durare parecchio. Nella scheda «Job Queues» potete seguire Immich mentre elabora le foto.

Il caricamento ad app aperta e quello in background sono due meccanismi separati. Quando l’app passa in background è il sistema operativo a decidere se e per quanto far girare il caricamento, di solito in base alle regole sul risparmio della batteria. Su iOS conviene attivare per Immich l’aggiornamento app in background (Settings > General > Background App Refresh) e disattivare la modalità a basso consumo quando non serve. Altri consigli sono nelle FAQ.

Il caricamento dal telefono non è un backup del server. Se il disco del server si guasta, le foto caricate sono a rischio. Immich ha backup integrati del database, ma il database contiene solo i metadati e le informazioni sugli utenti: foto e video in UPLOAD_LOCATION vanno copiati a parte, con un sistema vostro. Le istruzioni sono nella pagina ufficiale «Backup and Restore», a cui rimandano le FAQ.

Accesso da fuori casa, reverse proxy, HTTPS e machine learning su un’altra macchina restano fuori da questa guida.

Aggiornare Immich

Prima di ogni aggiornamento leggete le note di rilascio e l’elenco delle versioni con modifiche incompatibili, come raccomanda la pagina Upgrading. Le modifiche incompatibili dovrebbero arrivare solo con i cambi di versione principale. Il server funziona solo con app della stessa versione principale, mentre l’app di solito supporta anche quella precedente: per questo conviene aggiornare prima l’app sui telefoni e poi il server. Tornare a una versione precedente non è supportato.

Se nel .env avete fissato una versione precisa in IMMICH_VERSION, aggiornatela. Poi, dalla cartella del docker-compose.yml, scaricate le nuove immagini e riavviate:

docker compose pull && docker compose up -d

Le immagini della versione vecchia restano sul disco. Per recuperare spazio si eliminano le immagini Docker non più usate:

docker image prune

Disinstallare Immich e ripartire da zero

Attenzione: questo passaggio distrugge il database e azzera l’installazione. Il comando che segue rimuove i container e i volumi di Immich. Se volete solo fermare Immich, non usatelo. Lanciatelo solo dalla cartella immich-app, e solo se volete davvero ricominciare da capo:

docker compose down -v

Per avere un’installazione pulita bisogna poi cancellare a mano due cartelle. Prima di farlo, controllate nel .env quali percorsi avete indicato:

• DB_DATA_LOCATION: contiene il database, le informazioni sui file e le impostazioni;
• UPLOAD_LOCATION: contiene tutte le foto e i video caricati. Se la cancellate senza averne una copia, li perdete.

Una volta cancellate le due cartelle, riavviando i container si ottiene un’installazione nuova di Immich. Se usate Portainer, fermate lo stack da lì, rimuovete i volumi di Immich nella sezione dei volumi e riavviate lo stack.

Se qualcosa va storto

Questi sono i problemi elencati nelle pagine Docker Compose e FAQ. Per leggere i log dei container si usa il comando docker logs della CLI di Docker.

• Errori come unknown shorthand flag: 'd' in -d oppure permission denied sul file .env: probabilmente state usando una versione sbagliata di Docker; la documentazione cita come esempio il pacchetto docker.io di Ubuntu 22.04.3 LTS. Seguite la procedura completa di installazione di Docker Engine per la vostra distribuzione, comprese le sezioni «Uninstall old versions» e «Install using the apt/rpm repository», che sostituiscono i pacchetti della distribuzione con quelli ufficiali di Docker.
• Avete scritto docker-compose invece di docker compose: su Ubuntu 22.04 senza modifiche il comando fallisce con un messaggio che dichiara non valido il file docker-compose.yml. Anche qui la soluzione è installare Docker dal repository ufficiale e usare docker compose.
• can't set healthcheck.start_interval as feature require Docker Engine v25 or later: commentate la riga start_interval nella sezione del database del docker-compose.yml.
• FATAL: data directory "/var/lib/postgresql/data" has wrong ownership: l’errore è probabilmente legato a un problema del file system. Verificate dove si trova la cartella del database: NTFS ed exFAT/FAT32 non sono supportati. Se è così, spostatela oppure usate il volume pgdata descritto sopra.
• Il machine learning segnala worker che si chiudono: se il messaggio dice solo che il worker sta uscendo, è normale e serve a liberare RAM. Con SIGKILL o il codice 137, la causa più probabile è che il servizio stia esaurendo la memoria. Con SIGILL o il codice 132 la CPU probabilmente non è compatibile con Immich.
• L’app non riesce più ad accedere dopo un aggiornamento: controllate che app e server abbiano la stessa versione principale e secondaria. Gli store possono metterci qualche giorno ad approvare la nuova app; nel frattempo su Android si può installare l’APK da GitHub. Verificate anche le credenziali accedendo dal browser.

Documentazione di riferimento

Pagine consultate l’11 ottobre 2026:

• Immich: Quick start
• Immich: Docker Compose
• Immich: Environment Variables
• Immich: Requirements
• Immich: Upgrading
• Immich: FAQ

Leggi anche

• Tailscale: come raggiungere la rete di casa da fuori senza aprire porte
• Raspberry Pi Connect e SSH a chiave: come accedere al Pi da remoto
• Syncthing su Raspberry Pi: come installarlo e sincronizzare i file