Jellyfin con Docker Compose: come installarlo e collegare TV e smartphone

Jellyfin è un server multimediale che riunisce in un unico catalogo i film, le serie e la musica che avete su disco. Li rende disponibili nel browser, sulla smart TV e sullo smartphone. Chi cerca un’alternativa a Plex da far girare sul proprio hardware lo trova spesso tra le prime opzioni. Questa guida è per chi ha già Docker su un computer Linux e vuole avviare Jellyfin in un container con Docker Compose. Si parte dall’immagine ufficiale e si arriva al wizard iniziale. Poi si aggiungono le librerie, si creano gli utenti di casa e si collegano le app. I comandi sono quelli della documentazione ufficiale, elencata in fondo.

Cosa serve

• Un computer con Linux che faccia da server. Secondo la pagina Container di Jellyfin, il container è supportato solo su Linux. Su Windows e macOS si può avviare, ma non è supportato e alcune funzioni non vanno: se ne parla più avanti.
• Docker con il plugin Compose, installati seguendo la guida ufficiale di Docker. La documentazione di Docker Compose chiede l’ultima versione di Compose e una conoscenza di base di come funziona Docker.
• Una cartella con i vostri file multimediali: video di famiglia, CD di vostra proprietà convertiti in file, film acquistati senza DRM.
• Un dispositivo nella stessa rete con un browser, per la configurazione.

La pagina sull’installazione avverte che FreeBSD e i sistemi derivati, come TrueNAS CORE, non sono supportati. TrueNAS SCALE invece è basato su Linux ed è supportato tramite l’app del suo repository. Per scegliere l’hardware, la stessa pagina rimanda alla Hardware Selection Guide del progetto.

Scaricare l’immagine ufficiale e creare le cartelle persistenti

L’immagine ufficiale si chiama jellyfin/jellyfin. È basata su Debian e viene compilata direttamente dal codice sorgente di Jellyfin. Esistono anche immagini di terze parti, come quelle di LinuxServer.io e hotio, ma qui si usa quella ufficiale. Si scarica così:

docker pull jellyfin/jellyfin

Senza indicare un tag si ottiene latest, che segue sempre l’ultima versione stabile, anche quando cambia la versione maggiore. Chi preferisce restare su un ramo preciso può usare tag come 10 (versione maggiore), 10.11 (versione minore) o 10.11.0 (una release precisa).

Configurazione e cache vanno salvate fuori dal container, così restano anche quando il container viene ricreato. La strada più semplice è creare due cartelle sul computer host:

1. create prima una cartella jellyfin nella vostra home, con il file manager o come preferite: più avanti conterrà anche il file docker-compose.yml;
2. poi create al suo interno le due sottocartelle con i comandi qui sotto.

mkdir /path/to/config

mkdir /path/to/cache

/path/to/config e /path/to/cache sono segnaposto: sostituiteli con percorsi reali prima di dare il comando. Se la vostra home è /home/mario, diventano /home/mario/jellyfin/config e /home/mario/jellyfin/cache. Sono questi i percorsi usati negli esempi che seguono. Segnatevi quelli che scegliete, perché servono nel file di configurazione.

In alternativa si possono usare due volumi gestiti da Docker, jellyfin-config e jellyfin-cache, più facili da salvare con programmi esterni. Per un’installazione semplice, però, le cartelle montate sono considerate più comode.

Scrivere il file docker-compose.yml

Con Docker Compose tutte le impostazioni del container stanno in un file di testo invece che in un lungo comando. Nella cartella /home/mario/jellyfin create un file di testo chiamato docker-compose.yml. Il punto di partenza è il blocco YAML di esempio della pagina Container: copiatelo da lì e cambiate i percorsi. Così com’è, però, l’esempio non si avvia: contiene righe facoltative con valori segnaposto che vanno tolte o compilate.

Le righe da togliere

Nell’esempio ufficiale alcune parti sono precedute da un commento che inizia con # Optional. Se non vi servono, toglietele per intero, ciascuna insieme al proprio commento e al proprio blocco:

• la riga user: uid:gid con il commento sopra. Senza questa riga il container usa l’utente predefinito. Se volete tenerla, uid e gid vanno sostituiti con i numeri veri dell’utente e del gruppo: scritta alla lettera non è un utente valido;
• il mount dei font aggiuntivi, dal commento fino al suo read_only: true, cioè le righe - type: bind, source: /path/to/fonts, target: /usr/local/share/fonts/custom e read_only: true. La cartella /path/to/fonts non esiste: va tolta, oppure sostituita con una cartella di font reale;
• environment: con la variabile JELLYFIN_PublishedServerUrl=http://example.com e il commento sopra. example.com è un indirizzo d’esempio, non il vostro;
• extra_hosts: con il valore 'host.docker.internal:host-gateway' e il commento sopra. Secondo l’esempio Jellyfin, questa voce può essere necessaria per far passare l’healthcheck quando si usa la rete in modalità host.

L’esempio monta anche una seconda cartella su /media2. Se i vostri file stanno tutti in un posto solo, togliete anche quel blocco: - type: bind, source: /path/to/media2, target: /media2 e read_only: true.

Il file minimo

Tolte le righe facoltative, resta un file con questa struttura. Ogni livello dell’elenco corrisponde a un rientro di due spazi in più nel file. Nell’esempio la cartella dei file multimediali è /home/mario/Media. Attenzione: nell’esempio ufficiale il mount su /media non ha read_only: true, mentre quello su /media2 sì. Se volete i file multimediali in sola lettura, aggiungete read_only: true nel blocco di /media, allineato a source e target. La struttura qui sotto lo include:

• services: (senza rientro)
  • jellyfin:
    • image: jellyfin/jellyfin
    • container_name: jellyfin
    • ports:
      • - 8096:8096/tcp
      • - 7359:7359/udp
    • volumes:
      • - /home/mario/jellyfin/config:/config
      • - /home/mario/jellyfin/cache:/cache
      • - type: bind, poi sotto, allineate a type, le righe source: /home/mario/Media, target: /media e read_only: true
    • restart: 'unless-stopped'

Ecco cosa fanno queste voci:

• image indica l’immagine ufficiale scaricata prima;
• la porta 8096 TCP serve per l’interfaccia web, la 7359 UDP per la ricerca automatica del server nella rete di casa;
• i due volumi collegano le cartelle config e cache dell’host a /config e /cache nel container;
• il bind mount porta la cartella dei vostri file dentro il container come /media. Con read_only: true Jellyfin può leggere i file ma non modificarli;
• restart: 'unless-stopped' fa ripartire il container da solo finché non lo fermate voi.

Partite dall’esempio ufficiale togliendo le righe, invece di riscriverlo da zero, così mantenete i rientri giusti. In YAML il rientro conta: usate spazi e non tabulazioni, e tenete allineate le voci dello stesso livello. Un rientro sbagliato basta a far rifiutare il file da Compose.

Il container usa la rete in modalità bridge, quella predefinita di Docker. La modalità host è facoltativa, ma serve per usare DLNA.

Avviare il container e verificare che funzioni

Aprite un terminale nella cartella che contiene docker-compose.yml. Il primo avvio conviene farlo in primo piano: i messaggi del server scorrono a schermo e un errore nel file salta subito all’occhio.

docker compose up

Se il file è scritto bene, Compose crea il container e nel terminale compaiono i log di avvio di Jellyfin. Quando avete visto che parte, interrompete l’avvio in primo piano con Ctrl+C. Poi rilanciatelo in background aggiungendo -d, come suggerisce la pagina di Jellyfin:

docker compose up -d

Così il terminale resta libero. Per seguire i log in tempo reale in qualsiasi momento:

docker compose logs -f

L’opzione -f mostra i log man mano che arrivano. Con Ctrl+C smettete di seguirli e il container resta acceso.

Completare il wizard iniziale

Dal browser di un dispositivo della stessa rete aprite http://indirizzo-IP-del-server:8096, mettendo al posto della prima parte l’indirizzo IP del computer che ospita Docker. Si apre il wizard di configurazione, con queste schermate:

1. Select Language: la lingua scelta qui vale solo per il client che state usando. Quella del server si imposta dopo.
2. Setup Administrator Account: create l’account amministratore con una password robusta. Altri utenti, anche amministratori, si aggiungono a wizard finito.
3. Add Media Libraries: potete aggiungere subito le librerie con il pulsante +, oppure saltare il passaggio con Next e farlo dopo, come descritto più sotto.
4. Set a Preferred Metadata Language: lingua e paese predefiniti per scaricare i metadati, per esempio Italian e Italy. Se mancano informazioni in italiano, Jellyfin può prenderle in altre lingue. L’impostazione si può cambiare anche libreria per libreria.
5. Networking Settings: per la maggior parte degli utenti si consiglia di attivare Allow remote access to this server. L’opzione automatic port mapping va invece lasciata spenta, salvo necessità precise, perché si basa su UPnP, un protocollo associato a problemi di sicurezza.
6. Next Steps: la pagina finale, con i rimandi alle configurazioni successive.

A quel punto potete accedere con l’account amministratore.

Aggiungere le librerie di film, serie e musica

Una libreria è una raccolta virtuale di contenuti e può mettere insieme cartelle diverse. Per crearne una seguite la pagina sulle librerie: aprite il menu dell’interfaccia web e scegliete Admin > Dashboard. Poi, nel menu a sinistra, andate su Server > Libraries e premete Add Media Library.

Nel popup scegliete il tipo dal menu Content Type, scrivete un nome nel campo Display Name e aggiungete le cartelle con il pulsante +. Qui c’è il punto che confonde di più chi usa Docker: Jellyfin vede le cartelle dall’interno del container. Bisogna quindi indicare /media, o una sua sottocartella, e non il percorso del disco sul computer host, come /home/mario/Media. Se nella finestra di selezione non trovate la cartella, potete scrivere il percorso a mano. Se le cartelle dei file proprio non compaiono, il wizard indica un possibile problema di permessi.

Una configurazione tipica per una famiglia:

• Movies per i film, per esempio /media/Film, con i video delle vacanze montati e i film acquistati senza DRM;
• Shows per le serie;
• Music per gli album ricavati dai vostri CD.

Film, serie e musica sono i tipi con il supporto migliore nelle app. Esistono anche librerie per libri e foto, e un tipo misto per le cartelle con contenuti diversi. Il tipo misto però è sconsigliato, perché i metadati sono poco affidabili: meglio una libreria dedicata per ogni tipo. Una libreria può avere più percorsi, che compaiono tutti insieme. Dopo la conferma, in cima alla pagina compare una barra di avanzamento che mostra la scansione dei file.

Creare gli utenti

Un utente per ogni persona di casa tiene separati i progressi di visione e permette di limitare i contenuti. Seguendo la pagina sulla gestione degli utenti, andate in Dashboard > Users e premete il simbolo + in cima alla pagina. Inserite il nome dell’utente, che compare nella schermata di accesso oppure va digitato lì. Tra le opzioni avanzate c’è Hide this user from login screens, che nasconde l’utente dalla schermata di accesso: in quel caso nome e password vanno scritti a mano.

L’opzione Enable access to all libraries è attiva di default. Se la disattivate, potete scegliere libreria per libreria, per esempio per un profilo dei bambini che vede soltanto i cartoni. Attenzione: chi non ha accesso a tutte le librerie non riceve in automatico quelle create in seguito, che vanno abilitate a mano. Confermate con Save.

Per modificare un utente cliccate sul suo ritratto oppure sul simbolo …. Le schede sono Profile, Library Access, Parental Control e Password. Nella scheda Password impostate la password, che poi l’utente può cambiare dalle proprie impostazioni. In Parental Control si limita la classificazione massima dei contenuti o si definiscono le fasce orarie di accesso. Ogni modifica va salvata con Save in fondo alla pagina. Date i permessi amministrativi solo a chi gestisce davvero il server.

Collegare le app su smart TV e smartphone

Jellyfin ha app client per smart TV, box multimediali e smartphone. L’elenco dei client ufficiali, con gli store da cui scaricarli, è sul sito del progetto, nella sezione dei download. Conviene installare solo le app indicate lì, dagli store elencati.

Il collegamento funziona allo stesso modo in tutte le app:

1. aprite l’app e, quando chiede un server, inserite http://indirizzo-IP-del-server:8096;
2. nella rete di casa l’app può anche trovare il server da sola, grazie alla porta 7359/udp per la ricerca automatica pubblicata nel file Compose;
3. accedete con uno degli utenti creati al passaggio precedente.

L’accesso da fuori casa è un argomento a parte: la documentazione del wizard rimanda al Networking Guide di Jellyfin.

Aggiornare, fermare o rimuovere Jellyfin

Jellyfin non ha un meccanismo per tornare indietro di versione: al primo avvio con una versione nuova i dati vengono migrati e non funzionano più con la vecchia. Anche la pagina Container ricorda che per ripristinare una versione precedente serve un backup. Prima di aggiornare, quindi, fermate il server e copiate la cartella di configurazione.

Dalla cartella del file Compose, il comando qui sotto ferma Jellyfin e rimuove il container. Elimina il container e i dati scritti al suo interno, ma non tocca le cartelle montate dall’host, cioè configurazione, cache e file multimediali. Le riproduzioni in corso si interrompono:

docker compose down

A server fermo, copiate in un posto sicuro l’intera cartella dell’host montata su /config, che contiene dati e configurazione: nell’esempio è /home/mario/jellyfin/config. Copiarla con Jellyfin acceso rischia di salvare un database bloccato e non recuperabile. Poi scaricate l’immagine aggiornata:

docker pull jellyfin/jellyfin

Infine rilanciate Compose in background. Il container viene ricreato con l’immagine appena scaricata, mentre configurazione, cache e file multimediali restano nelle cartelle dell’host:

docker compose up -d

Per fermare Jellyfin senza aggiornarlo basta lo stesso docker compose down: il server non risponde più finché non lo riavviate con docker compose up -d. Per disinstallare del tutto, dopo averlo fermato cancellate a mano le cartelle config e cache, controllando bene i percorsi: lì ci sono utenti, librerie e impostazioni, e una volta cancellate non si recuperano. La cartella dei vostri file non va toccata. Infine cancellate l’immagine da Docker.

Windows, macOS e approfondimenti

Su questo la pagina Container è chiara: su Windows e macOS bisogna installare Jellyfin in modo nativo. Su questi sistemi il container non è supportato e alcune funzioni non vanno, in particolare la transcodifica con accelerazione hardware e la scansione delle librerie su macOS in Docker. Chi usa Windows o macOS trova le istruzioni per il proprio sistema nella pagina sull’installazione, che ha una sezione per ciascuno.

Ci sono altri due argomenti da approfondire:

• accelerazione hardware: la pagina Next Steps del wizard la suggerisce per migliorare le prestazioni o ridurre i consumi. La configurazione cambia in base alla GPU, quindi va seguita nella sezione Hardware Acceleration della documentazione di Jellyfin;
• accesso remoto: Next Steps suggerisce di configurarlo per usare Jellyfin fuori casa. I dettagli sono nel Networking Guide citato nella schermata Networking Settings.

Jellyfin si affianca bene ad altri servizi da tenere in casa: Immich per le foto, Syncthing per tenere allineata la cartella dei file multimediali tra più computer e Pi-hole per filtrare pubblicità e tracciamento in tutta la rete. Su opengeek.it trovate una guida per ciascuno.

Documentazione di riferimento

Pagine consultate il 12 ottobre 2026:

• Jellyfin — Container (Docker, Podman)
• Docker — Docker Compose Quickstart
• Jellyfin — Installation
• Jellyfin — Setup Wizard
• Jellyfin — Libraries
• Jellyfin — Adding and Managing Users
• Jellyfin — Backup and Restore

Leggi anche

• Immich con Docker Compose: come installarlo e caricare le foto dal telefono
• Tailscale: come raggiungere la rete di casa da fuori senza aprire porte
• Home Assistant OS su Raspberry Pi 4 o 5: guida all’installazione