Installer Jellyfin sur Debian ou Ubuntu
Installez Jellyfin depuis son dépôt officiel, publiez-le en HTTPS avec Caddy, gérez les comptes et comprenez les limites du transcodage sans GPU, avec mises à jour et sauvegardes.
Sur cette page
Vos valeurs
Renseignez-les une fois, les commandes du guide se mettent à jour.
Ce guide vous explique comment installer Jellyfin, un serveur multimédia libre, depuis son dépôt officiel. L’assistant de configuration se fait à travers un tunnel SSH, puis Caddy publie le service en HTTPS.
À la fin du guide, Jellyfin répond sur https://jellyfin.votre-domaine.com, son port reste fermé depuis Internet, chaque personne dispose de son compte et vous savez ce que votre serveur peut réellement diffuser sans carte graphique.
Commander un serveur
Ce guide s’applique aux serveurs que vous administrez vous-même :
Prérequis
- Un serveur amd64 ou arm64 sous Debian 12 ou 13, ou Ubuntu 22.04 ou 24.04
- Un accès SSH avec un utilisateur disposant de
sudo - UFW actif, configuré avec le guide Configurer le pare-feu UFW sans perdre l’accès SSH
- Caddy, installé avec le guide Caddy en reverse proxy avec HTTPS automatique
- Un enregistrement DNS A pour
jellyfin.votre-domaine.comversVOTRE_IP_SERVEUR, par exemple avec le guide Créer un enregistrement A - Assez d’espace disque pour vos médias, les métadonnées et le cache de transcodage
La documentation de Jellyfin recommande 8 Go de mémoire et un SSD de 100 Go pour le système, les fichiers de Jellyfin et le cache de transcodage, hors médias. Pour l’accès à distance, elle conseille au moins 20 Mbit/s en envoi.
Ports utilisés
| Port | Sens | Rôle | À ouvrir |
|---|---|---|---|
| 80/tcp | Entrant | Validation du certificat et redirection vers HTTPS | Oui |
| 443/tcp | Entrant | Accès HTTPS à Jellyfin | Oui |
| 443/udp | Entrant | HTTP/3 | Recommandé |
| 8096/tcp | Local | Interface HTTP de Jellyfin | Non |
| 8920/tcp | Local | HTTPS intégré, inutilisé ici | Non |
| 7359/udp | Local | Découverte sur réseau local, inutile sur un serveur distant | Non |
Étape 1 : vérifier le pare-feu
sudo ufw status verbose
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udpLa première commande doit indiquer Status: active et une politique entrante deny. Si ce n’est pas le cas, arrêtez-vous et activez UFW. N’ajoutez aucune règle pour 8096.
Étape 2 : ajouter le dépôt officiel
Installez les outils nécessaires et la clé de signature du dépôt :
sudo apt update
sudo apt install -y curl gnupg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key | sudo gpg --dearmor --yes -o /etc/apt/keyrings/jellyfin.gpgSur Ubuntu uniquement, activez le composant Universe, qui fournit des dépendances de FFmpeg :
sudo apt install -y software-properties-common
sudo add-apt-repository -y universeDéclarez ensuite le dépôt :
export VERSION_OS="$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release)"
export VERSION_CODENAME="$(awk -F'=' '/^VERSION_CODENAME=/{ print $NF }' /etc/os-release)"
export DPKG_ARCHITECTURE="$(dpkg --print-architecture)"
cat <<EOF | sudo tee /etc/apt/sources.list.d/jellyfin.sources
Types: deb
URIs: https://repo.jellyfin.org/${VERSION_OS}
Suites: ${VERSION_CODENAME}
Components: main
Architectures: ${DPKG_ARCHITECTURE}
Signed-By: /etc/apt/keyrings/jellyfin.gpg
EOF
sudo apt updateÉtape 3 : installer une version précise
Jellyfin demande de ne pas sauter de version majeure lors des mises à jour. Ce guide installe donc une version choisie, puis la bloque pour qu’un apt upgrade ne la change pas sans vous.
Les paquets portent un suffixe propre à votre système, par exemple deb13 ou ubu2404 :
. /etc/os-release
case "$ID" in
debian) SUFFIX="deb${VERSION_ID}" ;;
ubuntu) SUFFIX="ubu$(echo "$VERSION_ID" | tr -d .)" ;;
esac
echo "$SUFFIX"
apt-cache madison jellyfin-server | head -n 5Installez la version, puis bloquez-la :
sudo apt install -y "jellyfin=12.4+${SUFFIX}" "jellyfin-server=12.4+${SUFFIX}" "jellyfin-web=12.4+${SUFFIX}"
sudo apt-mark hold jellyfin jellyfin-server jellyfin-webLe paquet installe aussi jellyfin-ffmpeg, la version de FFmpeg adaptée à Jellyfin. Contrôlez le service :
systemctl status jellyfin --no-pager
curl -fsS http://127.0.0.1:8096/healthLa dernière commande doit renvoyer Healthy. Depuis votre poste, le port doit rester fermé :
nc -vz -w 5 VOTRE_IP_SERVEUR 8096Cette commande doit échouer. Si nc n’est pas disponible, ouvrez http://VOTRE_IP_SERVEUR:8096 dans un navigateur : la page ne doit pas se charger. Si la connexion réussit, arrêtez Jellyfin avec sudo systemctl stop jellyfin et corrigez le pare-feu avant de continuer.
Étape 4 : préparer les médias
Créez un dossier lisible par le service Jellyfin, dans lequel votre utilisateur peut écrire :
sudo mkdir -p /srv/media/movies /srv/media/shows /srv/media/music
sudo chown -R VOTRE_USER:jellyfin /srv/media
sudo chmod -R u=rwX,g=rX,o= /srv/media
sudo find /srv/media -type d -exec chmod g+s {} +Depuis votre poste, envoyez vos fichiers avec rsync :
rsync -avh --progress ./my-videos/ VOTRE_USER@VOTRE_IP_SERVEUR:/srv/media/movies/Étape 5 : terminer l’assistant par un tunnel SSH
Depuis votre poste, ouvrez un tunnel et laissez cette session ouverte :
ssh -L 8096:127.0.0.1:8096 VOTRE_USER@VOTRE_IP_SERVEUROuvrez http://localhost:8096, puis suivez l’assistant :
- Choisissez la langue.
- Créez le compte administrateur avec un mot de passe long et unique.
- Ajoutez vos médiathèques en sélectionnant les dossiers de
/srv/media, ou passez cette étape. - Choisissez la langue des métadonnées.
- Laissez Autoriser les connexions distantes à ce serveur coché : derrière le proxy, vos visiteurs seront vus comme distants.
Étape 6 : limiter Jellyfin à la boucle locale
Connectez-vous, puis ouvrez Tableau de bord > Réseau et renseignez :
| Champ | Valeur | Rôle |
|---|---|---|
| Lier à l’adresse de réseau local | 127.0.0.1 |
Jellyfin n’écoute plus que sur le serveur |
| Proxies connus | 127.0.0.1 |
Jellyfin accepte les en-têtes X-Forwarded-* de Caddy |
Enregistrez, puis redémarrez le service et contrôlez l’écoute :
sudo systemctl restart jellyfin
sudo ss -ltnp | grep 8096
sudo grep -A1 -E '<(KnownProxies|LocalNetworkAddresses)>' /etc/jellyfin/network.xmlLe port doit apparaître sur 127.0.0.1:8096 uniquement. Le tunnel SSH continue de fonctionner.
Sans proxy connu, Jellyfin ignore l’adresse transmise par Caddy et considère tous les visiteurs comme locaux : les restrictions d’accès distant ne s’appliquent alors plus.
Étape 7 : publier Jellyfin en HTTPS
Ajoutez ce site dans /etc/caddy/Caddyfile, ou dans un fichier de /etc/caddy/sites/ :
jellyfin.votre-domaine.com {
reverse_proxy 127.0.0.1:8096
}Caddy transmet les WebSockets utilisés par Jellyfin sans réglage particulier. N’activez pas de journal d’accès complet sur ce site : certaines URL de Jellyfin peuvent contenir un paramètre api_key.
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyVérifier le résultat
curl -I http://jellyfin.votre-domaine.com
curl -fsS https://jellyfin.votre-domaine.com/healthLa première commande doit renvoyer une redirection 308 vers HTTPS, la seconde Healthy. Connectez-vous ensuite sur https://jellyfin.votre-domaine.com, lancez une vidéo et vérifiez qu’elle démarre. Dans les applications Jellyfin, indiquez cette même adresse comme serveur.
Gérer les comptes
Dans Tableau de bord > Utilisateurs, créez un compte par personne avec Ajouter un utilisateur. Utilisez vous-même un compte sans droits d’administration pour regarder vos contenus.
Pour chaque compte, contrôlez ces réglages :
- limitez l’accès aux seules médiathèques utiles ;
- activez Ne pas afficher cet utilisateur sur les écrans de connexion pour ne pas exposer la liste des comptes ;
- renseignez Tentatives de connexion avant verrouillage du compte, par exemple avec
5. Ce verrouillage n’est pas actif par défaut, et le compte est désactivé une fois le seuil atteint ; - décochez Autoriser la lecture de vidéos nécessitant un transcodage si le serveur ne peut pas suivre.
Jellyfin ne propose pas de double authentification native : imposez des mots de passe longs et uniques. Pour réactiver un compte verrouillé, un administrateur décoche Désactiver cet utilisateur dans son profil. Gardez donc un second compte administrateur de secours.
Comprendre les limites sans GPU
Jellyfin peut lire un fichier de quatre façons, de la plus légère à la plus coûteuse :
| Mode | Traitement | Charge du serveur |
|---|---|---|
| Direct Play | Fichier envoyé tel quel | Quasi nulle |
| Remux | Conteneur changé, flux conservés | Faible |
| Direct Stream | Audio converti, vidéo conservée | Faible à modérée |
| Transcode | Vidéo réencodée à la volée | Très élevée |
Pour rester dans de bonnes conditions :
- Privilégiez des formats lus nativement par vos appareils, en consultant le tableau de compatibilité des codecs.
- Contrôlez le mode de lecture dans le tableau de bord pendant une diffusion : il indique si une vidéo est transcodée et pourquoi.
- Bloquez le transcodage vidéo pour les comptes concernés. Un fichier incompatible peut alors refuser de se lire, mais il ne saturera plus le serveur.
- Limitez les threads dans Tableau de bord > Lecture > Transcodage, avec Nombre de threads de transcodage. Le serveur reste réactif, mais la lecture peut saccader.
- Évitez une limite de débit trop basse dans Lecture > Diffusion. Une vidéo dont le débit dépasse Limite de débit de streaming Internet est transcodée pour s’y adapter.
- Surveillez le disque : les fichiers temporaires vont dans
/var/cache/jellyfin/transcodes. Prévoyez environ la taille de votre plus gros fichier, multipliée par le nombre de flux simultanés.
Si votre serveur dispose d’un GPU compatible, suivez la documentation Accélération matérielle. Tenez aussi compte de la bande passante et du volume de trafic de votre offre : chaque flux consomme un débit proche de celui du fichier.
Mettre à jour Jellyfin
Jellyfin ne sait pas revenir en arrière : au premier démarrage, les migrations modifient les données. Lisez les notes de version et sauvegardez avant toute mise à jour.
Consultez la version installée et celles disponibles :
jellyfin --version
sudo apt update
apt-cache madison jellyfin-serverAprès la sauvegarde, remplacez 12.4 par la version cible :
. /etc/os-release
case "$ID" in
debian) SUFFIX="deb${VERSION_ID}" ;;
ubuntu) SUFFIX="ubu$(echo "$VERSION_ID" | tr -d .)" ;;
esac
TARGET=12.4
sudo apt-mark unhold jellyfin jellyfin-server jellyfin-web
sudo apt install -y "jellyfin=${TARGET}+${SUFFIX}" "jellyfin-server=${TARGET}+${SUFFIX}" "jellyfin-web=${TARGET}+${SUFFIX}"
sudo apt-mark hold jellyfin jellyfin-server jellyfin-web
sudo journalctl -u jellyfin --no-pager -n 50Sauvegarder et restaurer
Depuis Jellyfin 10.11, Tableau de bord > Sauvegardes > Créer une sauvegarde produit une archive pendant que le serveur tourne. Elle est stockée dans /var/lib/jellyfin/data/backups, avec au moins 5 Go libres requis, et se restaure depuis la même page. Copiez ces archives hors du serveur.
La méthode manuelle convient avant une mise à jour, car elle conserve toute la configuration et s’effectue service arrêté :
sudo systemctl stop jellyfin
sudo mkdir -p /var/backups/jellyfin
sudo tar -czpf "/var/backups/jellyfin/jellyfin-$(date +%F)-$(dpkg-query -W -f='${Version}' jellyfin-server).tar.gz" /etc/jellyfin /var/lib/jellyfin
sudo systemctl start jellyfin
sudo chmod -R go-rwx /var/backups/jellyfinLe nom du fichier contient la version : restaurez-le avec cette même version. Vérifiez que l’archive contient la base :
sudo sh -c 'tar -tzf "$(ls -1t /var/backups/jellyfin/*.tar.gz | head -n 1)" | grep "jellyfin.db$"'Pour restaurer, remplacez le nom de l’archive :
ARCHIVE=/var/backups/jellyfin/jellyfin-2026-11-18-12.4+deb13.tar.gz
sudo systemctl stop jellyfin
sudo mv /var/lib/jellyfin /var/lib/jellyfin.bak
sudo mv /etc/jellyfin /etc/jellyfin.bak
sudo tar -xzpf "$ARCHIVE" -C /
sudo systemctl start jellyfinCes sauvegardes ne contiennent pas vos médias. Conservez /srv/media séparément, par exemple avec rsync vers un autre emplacement.
En cas de problème
Unable to locate package jellyfin ou erreur de dépôt
Contrôlez le fichier du dépôt et le nom de votre version :
cat /etc/apt/sources.list.d/jellyfin.sources
sudo apt updateSuites doit valoir bookworm, trixie, jammy ou noble. URIs doit se terminer par debian ou ubuntu.
Version '12.4+...' for 'jellyfin' was not found
La variable SUFFIX est vide ou la version n’existe pas pour votre système. Lancez echo "$SUFFIX", puis comparez avec apt-cache madison jellyfin-server.
Dépendances de jellyfin-ffmpeg non satisfaites sur Ubuntu
Le composant Universe n’est pas activé. Reprenez la commande add-apt-repository de l’étape 2, puis sudo apt update.
address already in use
Un autre programme utilise le port 8096 :
sudo ss -ltnp | grep 8096
sudo journalctl -u jellyfin --no-pager -n 50Erreur 502 dans le navigateur
Jellyfin est arrêté ou n’écoute pas sur 127.0.0.1:8096. Vérifiez avec systemctl status jellyfin --no-pager et curl -fsS http://127.0.0.1:8096/health. Au premier démarrage après une mise à jour, les migrations peuvent prendre du temps.
Interface inaccessible après une modification du réseau
Corrigez directement la configuration, service arrêté :
sudo systemctl stop jellyfin
sudo nano /etc/jellyfin/network.xml
sudo systemctl start jellyfinLocalNetworkAddresses et KnownProxies doivent contenir chacun <string>127.0.0.1</string>.
Les connexions distantes sont refusées
Vérifiez que Autoriser les connexions distantes à ce serveur est coché dans Tableau de bord > Réseau, et que le profil de l’utilisateur l’autorise aussi.
Une médiathèque reste vide
Le service n’a probablement pas accès aux fichiers :
sudo -u jellyfin ls -la /srv/media/moviesEn cas de Permission denied, reprenez les commandes de l’étape 4, puis relancez l’analyse de la médiathèque.
La lecture saccade ou le processeur reste à 100 %
La vidéo est sans doute transcodée. Vérifiez le mode de lecture dans le tableau de bord, puis appliquez les conseils de la section sur les limites sans GPU. Les erreurs de conversion se trouvent dans les fichiers de /var/log/jellyfin :
sudo ls -lt /var/log/jellyfin | headNo space left on device pendant une lecture
Le cache de transcodage a rempli le disque :
df -h /var/cache/jellyfin
sudo du -sh /var/cache/jellyfin/transcodes