Immich è il server fotografico open source che più si avvicina a Google Foto: backup automatico dallo smartphone, ricerca per contenuto, riconoscimento dei volti, album condivisi, tutto su un disco vostro. Dai primi di luglio 2026 (la 3.0.0 è del 2 luglio) è alla serie 3.x e la versione stabile al momento in cui scriviamo è la 3.3.6 del 4 novembre 2026. Le guide italiane in circolazione, ferme alla serie 1.1xx, usano ancora docker-compose e l’estensione pgvecto.rs, due cose che Immich 3 non supporta più: qui rifacciamo il percorso da zero sulla documentazione ufficiale, dai due file di configurazione fino a backup e aggiornamenti.
In breve
- Tempo: 60–90 minuti, più il tempo di caricamento della libreria.
- Difficoltà: media.
- Cosa serve: un PC o mini PC con Linux a 64 bit (Ubuntu o Debian vanno benissimo), almeno 6 GB di RAM e 2 core, Docker Engine con il plugin Compose, un disco con spazio per le foto e un SSD locale per il database.
- Risultato: Immich raggiungibile sulla porta 2283 della rete di casa, con l’app Android o iOS che carica le foto da sola.
Versioni: Immich v3.3.6 (stabile del 4 novembre 2026), Docker Engine 25 o successivo con il plugin Compose, immich-go v0.32.0. La procedura segue la documentazione ufficiale di Immich (docs.immich.app) e le note di rilascio su GitHub, verificate il 9 novembre 2026. Le release 3.4.0-rc sono versioni candidate e non vanno usate su un server domestico.
Prima di iniziare: requisiti e dove mettere i dati
La pagina dei requisiti di Immich è più esigente di quanto si pensi. Il minimo è 6 GB di RAM (8 consigliati) e 2 core (4 consigliati); con soli 4 GB il server parte solo disattivando il machine learning, quindi senza ricerca intelligente e senza volti. Dalla versione 3 il container di machine learning su amd64 richiede una CPU di livello x86-64-v2: secondo la documentazione la maggior parte dei processori dal 2012 circa lo supporta; i processori più vecchi, che spesso finiscono a fare da server di casa, restano fuori. Per arm64 la documentazione non indica questo requisito.
Due regole sul disco che la documentazione sottolinea:
- Le foto (
UPLOAD_LOCATION) vanno su un filesystem compatibile Unix con permessi e proprietari, come ext4 o ZFS. Mettete in conto il 10–20% di spazio in più rispetto alla libreria, perché Immich genera miniature e versioni transcodificate dei video. - Il database (
DB_DATA_LOCATION) deve stare su un SSD locale e mai su una condivisione di rete di alcun tipo. Occupa in genere 1–3 GB e, se usate limiti di risorse in Docker, gli servono almeno 2 GB di RAM.
Sul software, Immich richiede il comando docker compose (con lo spazio): il vecchio docker-compose con il trattino è deprecato e la documentazione dice esplicitamente che non è più supportato. Se Docker non c’è ancora, installatelo dal repository ufficiale come spieghiamo in https://hardwarfare.it/ai-software/linux/installare-docker-compose-ubuntu-debian/, non dai pacchetti della distribuzione.
Attenzione: Immich è pensato per Linux. La documentazione sconsiglia fortemente i sistemi non Linux (Windows e macOS con Docker Desktop), e su WSL il database non funziona nelle cartelle montate dall’host (sotto /mnt). Anche Docker dentro un container LXC, tipico su Proxmox, non è raccomandato: meglio una macchina virtuale.
Passo 1: controllare Docker e il disco
Collegatevi al server via SSH e verificate Docker, il plugin Compose e il filesystem della cartella che ospiterà le foto, per esempio /srv/foto:
docker compose version
df -Th /srv/fotoVerifica: il primo comando deve rispondere Docker Compose version v2.x; se dice “command not found”, il plugin manca. La colonna Type di df deve indicare ext4, zfs, btrfs o xfs: con ntfs, exfat, cifs o nfs il database non partirà.
Passo 2: scaricare i due file ufficiali
Immich si installa con due soli file, da prendere dall’ultima release su GitHub e non da guide di terzi:
mkdir ./immich-app
cd ./immich-app
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.envIl docker-compose.yml della 3.3.6 definisce quattro servizi: immich-server, immich-machine-learning, redis (in realtà l’immagine Valkey 9) e database, basato su ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0, il PostgreSQL con l’estensione VectorChord che ha sostituito pgvecto.rs. Se avete un vecchio file con tensorchord/pgvecto-rs, buttatelo e ripartite da questo.
Verifica: ls -la deve mostrare entrambi i file (.env è nascosto). Se li avete scaricati dal browser, rinominate example.env in .env.
Passo 3: compilare il file .env
Aprite .env con nano .env. Il file ufficiale contiene poche righe e solo quattro vanno toccate:
| Variabile | Valore predefinito | Cosa mettere |
|---|---|---|
UPLOAD_LOCATION | ./library | Cartella delle foto, per esempio /srv/foto |
DB_DATA_LOCATION | ./postgres | Cartella del database su SSD locale, per esempio /srv/immich-db |
TZ | commentata | Togliete il # e scrivete TZ=Europe/Rome |
DB_PASSWORD | postgres | Una password casuale con soli caratteri A-Za-z0-9 |
Il limite sui caratteri della password non è un vezzo: la documentazione avverte che simboli e spazi possono creare problemi all’interpretazione del file da parte di Docker. La riga IMMICH_VERSION=v3 va lasciata così: il tag v3 segue la versione maggiore corrente e salta le release candidate. Le altre variabili non vanno toccate. Create le due cartelle prima di avviare con sudo mkdir -p /srv/foto /srv/immich-db.
Verifica: grep -v '^#' .env | grep . stampa solo le righe attive: devono comparire i vostri percorsi, TZ=Europe/Rome e una password diversa da postgres.
Passo 4: avviare i container
Dalla cartella immich-app lanciate:
docker compose up -dIl primo avvio scarica quattro immagini e il modello di machine learning, quindi richiede qualche minuto. Poi controllate lo stato:
docker compose psVerifica: i quattro container devono essere Up e (healthy). Se immich_server resta a lungo in starting, leggete docker compose logs -f immich-server: al primo avvio esegue le migrazioni del database ed è normale che impieghi un po’.
Aprite dal PC http://IP-DEL-SERVER:2283 e fate clic su Getting Started: il primo utente registrato diventa amministratore e crea gli altri account da Administration > Users. In Administration > Settings > Storage Template si decide come organizzare i file sul disco: fatelo subito, perché le modifiche si applicano ai file già caricati solo lanciando il job Storage Template Migration dalla pagina dei job.
Passo 5: l’app sul telefono e il backup automatico
Installate l’app Immich da Google Play o dall’App Store e inserite l’indirizzo del server con la porta, per esempio http://192.168.1.50:2283. Nella sezione Backup scegliete gli album del telefono da caricare (di solito Camera e Screenshots) e attivate il backup in background con i permessi che l’app chiede. Immich raccomanda di aggiornare le app prima del server: l’app è compatibile con la versione maggiore corrente e quella precedente, il server solo con la propria.
Verifica: fate una foto e, con il telefono in Wi-Fi, aspettate qualche secondo: deve comparire nella timeline web. Se non parte, controllate che la cartella sia selezionata per il backup e che il risparmio energetico non blocchi l’app.
Passo 6: importare l’archivio di Google Foto
Il trasloco passa da Google Takeout: richiedete l’esportazione dei soli dati di Google Foto in archivi ZIP e non estraeteli (la documentazione di immich-go li legge così come sono; solo gli archivi .tgz vanno estratti prima). Per importarli mantenendo date, descrizioni e album lo strumento di riferimento è immich-go, un eseguibile a riga di comando per Linux, Windows, macOS e FreeBSD che si scarica dalle release su GitHub: la v0.32.0 del 25 giugno 2026 ha introdotto la compatibilità con Immich 3, quindi non usate versioni precedenti. Create una chiave API dal vostro profilo in Immich (Account Settings > API Keys) e lanciate l’importazione da una macchina che vede sia gli archivi sia il server, con la sintassi degli esempi della documentazione di immich-go:
./immich-go upload from-google-photos --server=http://192.168.1.50:2283 --api-key=LA-VOSTRA-CHIAVE /percorso/takeout-*.zipIl programma legge i file JSON di Google per ricostruire data di scatto e album e salta i duplicati già sul server. Per librerie da centinaia di gigabyte lanciatelo in una sessione tmux.
Verifica: aprite in Immich un album che esisteva su Google Foto e controllate date e numero di elementi; da Administration > Job Queues guardate che le code di miniature e metadati si svuotino. Finché il machine learning non ha finito, la ricerca per contenuto è parziale.
Passo 7: il backup, che non è opzionale
La documentazione lo dice senza giri di parole: Immich conserva percorsi e metadati nel database e non scansiona la cartella delle foto, quindi senza database le foto ci sono ma l’archivio è perduto. Servono due cose, salvate insieme.
Il database. Immich crea da solo un dump giornaliero alle 2:00 e ne conserva gli ultimi 14 in UPLOAD_LOCATION/backups; frequenza e numero si regolano in Administration > Settings > Database Dump Settings. Potete anche farne uno manuale da Administration > Job Queues > Create job > Create Database Dump. Chi preferisce lo script, con il nome del container e i valori di DB_DATABASE_NAME e DB_USERNAME del file .env ufficiale:
docker exec -t immich_postgres pg_dump --clean --if-exists --dbname=immich --username=postgres | gzip > immich-db-$(date +%F).sql.gzI file. Tutta la cartella UPLOAD_LOCATION, sottocartella backups compresa, va copiata su un altro disco e idealmente fuori casa, con la regola 3-2-1 descritta in https://hardwarfare.it/ai-software/linux/backup-automatici-server-restic-regola-3-2-1/. Il dump del database da solo non contiene nemmeno una foto.
Il ripristino si fa dall’interfaccia: su un’installazione nuova, dopo aver rimesso le cartelle al loro posto, la schermata di benvenuto offre Restore from backup e lascia scegliere il file .sql.gz; su un’installazione esistente la stessa funzione è in Administration > Maintenance.
Verifica: ls -lh /srv/foto/backups deve mostrare almeno un file .sql.gz. Un backup mai provato in ripristino non è un backup: una volta l’anno fatelo su una macchina virtuale.
Passo 8: aggiornare senza rompere nulla
Immich segue il versionamento semantico e riserva le modifiche incompatibili alle versioni maggiori, ma la documentazione chiede di leggere sempre le note di rilascio prima di aggiornare e rimanda a un elenco su GitHub, filtrato con l’etichetta changelog:breaking-change, delle versioni con modifiche incompatibili. Poi, dalla cartella immich-app:
docker compose pull && docker compose up -de, per liberare lo spazio delle immagini vecchie:
docker image pruneTre avvertenze dalla documentazione. Il tag v3 vi porterà alle 3.x successive ma non a una futura 4.0: il passaggio di versione maggiore andrà fatto a mano cambiando IMMICH_VERSION, dopo aver letto le note di rilascio. Tornare a una versione precedente non è supportato, nemmeno nella stessa serie minore: ecco perché il dump del database va fatto prima di ogni aggiornamento. E non esistono patch per le versioni vecchie: la 3.3.6 è uscita proprio per spegnere la telemetria che la libreria onnxruntime aveva acceso nel container di machine learning delle 3.3.x precedenti, inviando metriche anonime a Microsoft.
Verifica: dopo l’aggiornamento la versione del server mostrata nell’interfaccia di amministrazione deve corrispondere all’ultima release stabile su GitHub.
Passo 9: raggiungere Immich da fuori casa
La porta 2283 non va mai aperta sul router così com’è: il traffico passerebbe in chiaro, password comprese. Le due strade ragionevoli sono un reverse proxy con certificato HTTPS, come in https://hardwarfare.it/ai-software/linux/reverse-proxy-nginx-proxy-manager-caddy/, oppure Tailscale, che evita di esporre il server e funziona anche dietro CGNAT, il caso di molte connessioni FTTH e 5G italiane trattato in https://hardwarfare.it/guide-tecniche/guide-reti/cgnat-ip-pubblico-ddns-tailscale-cloudflare/. La pagina della documentazione sul reverse proxy ricorda di alzare il limite di dimensione dei caricamenti e i timeout (l’esempio per nginx usa client_max_body_size 50000M e 600 secondi), altrimenti i video lunghi del telefono si interrompono.
Se qualcosa va storto
unknown shorthand flag: 'd' in -d oppure permission denied sul file .env
Secondo la documentazione, state usando una versione sbagliata di Docker, tipicamente il pacchetto docker.io di Ubuntu. Rimuovete i pacchetti della distribuzione e installate dal repository ufficiale di Docker. Se invece avete digitato docker-compose con il trattino, l’errore è diverso: The Compose file './docker-compose.yml' is invalid because: 'name' does not match any of the regexes. La cura è la stessa.
can't set healthcheck.start_interval as feature require Docker Engine v25 or later
Il Docker installato è troppo vecchio. La documentazione suggerisce come ripiego di commentare la riga start_interval nella sezione del database, ma la soluzione vera è aggiornare Docker Engine almeno alla 25.
Il container di machine learning si riavvia in continuazione
Se docker compose ps mostra immich_machine_learning in Restarting su hardware datato, la causa più probabile è una CPU sotto il livello x86-64-v2 richiesto dalla v3. Secondo la documentazione l’ultima versione compatibile è la 2.7.5, che però non riceve più aggiornamenti e richiede un server della stessa versione: meglio cambiare macchina o rinunciare al machine learning.
Il database non parte
Quasi sempre DB_DATA_LOCATION punta a un filesystem non supportato: NTFS, exFAT, una condivisione SMB o NFS, oppure una cartella sotto /mnt in WSL. La documentazione indica come alternativa un volume Docker: nel file .env impostate DB_DATA_LOCATION=pgdata e in fondo al docker-compose.yml, sotto volumes:, aggiungete la riga pgdata: accanto a model-cache:.
Come tornare indietro
Per fermare Immich senza perdere nulla basta docker compose down dalla cartella immich-app: foto e database restano nelle cartelle indicate nel file .env e un successivo docker compose up -d ritrova tutto. Le foto sul telefono non vengono toccate finché non le cancellate voi dall’app: in caso di ripensamenti resta la copia sul dispositivo e, se lo avete conservato, l’archivio Takeout.
Guide collegate
- https://hardwarfare.it/ai-software/linux/installare-docker-compose-ubuntu-debian/: il prerequisito di questa guida.
- https://hardwarfare.it/ai-software/linux/installare-nextcloud-docker-aio-https/: l’alternativa per chi vuole anche documenti e calendario.
- https://hardwarfare.it/ai-software/linux/backup-automatici-server-restic-regola-3-2-1/: portare fuori casa foto e dump del database.
La nostra indicazione: Immich 3 è maturo quanto basta per diventare l’archivio fotografico di famiglia, a patto di rispettare le tre regole che la documentazione ripete in continuazione: database su SSD locale, backup di file e database insieme, note di rilascio lette prima di ogni aggiornamento. Chi le salta non ha un server fotografico, ha un singolo punto di guasto con una bella interfaccia.
Fonti
- Immich (installazione con Docker Compose)
- Immich (requisiti)
- Immich (release su GitHub)
- Immich (migrazione alla v3)
- Immich (aggiornamento)
- Immich (backup e ripristino)
- Immich (passi dopo l'installazione)
- immich-go (release su GitHub)
- immich-go (comando upload)
- Immich (reverse proxy)
Immagine di copertina: Smartphone photographer (Unsplash).jpg di James Sutton jamessutton_photography, licenza CC0, via Wikimedia Commons; elaborazione grafica HardWarfare.
Articolo redatto con il supporto di strumenti di intelligenza artificiale e verificato dalla redazione. Come usiamo l'AI · Come lavoriamo
