Jellyfin est un serveur multimédia libre et gratuit qui diffuse vos films, séries et musiques sur tous vos écrans, sans abonnement ni compte en ligne. Sur Linux, deux voies officielles cohabitent : le dépôt APT sur Debian et Ubuntu, le conteneur Docker partout ailleurs. Le point qui décide du confort réel n’est ni l’un ni l’autre, c’est le transcodage matériel : sans lui, un seul flux 4K sature un processeur entier.
Ce guide s’appuie sur l’image officielle jellyfin/jellyfin, et non sur celle de LinuxServer.io. Les deux fonctionnent, mais elles ne se configurent pas de la même façon, et confondre leurs conventions est une cause d’échec fréquente.
L’essentiel
- Version traitée : Jellyfin 10.11.11, publiée le 6 juin 2026
- Port par défaut : 8096 en HTTP, 7359 en UDP pour la découverte réseau
- Installation : dépôt APT officiel sur Debian, Ubuntu et dérivés ; conteneur Docker sur toutes les autres distributions
- Transcodage matériel : VA-API, QSV, NVENC et RKMPP sous Linux
- Accès distant : jamais le port 8096 exposé nu — VPN maillé ou reverse proxy avec HTTPS
- Rédigé d’après la documentation officielle Jellyfin, consultée le 4 septembre 2026. Les commandes
getent group render | cut -d: -f3etps -eo pcpu,pid,comm --sort=-pcpuont été exécutées et vérifiées ; les fichierscompose.yamlont été validés par un analyseur YAML. Le reste est conforme à la documentation à cette date, sans validation sur chaque configuration matérielle.
Jellyfin, Plex ou Emby : ce que vous gagnez et ce que vous perdez
Jellyfin est un fork d’Emby, créé en 2018 quand ce dernier est passé sous licence propriétaire. Il est intégralement gratuit : aucune fonction n’est réservée à un abonnement, et le serveur ne réclame aucun compte en ligne. Le prix de cette liberté est un travail de configuration que Plex fait à votre place.
| Critère | Jellyfin | Plex |
|---|---|---|
| Prix | Gratuit, sans option payante | Gratuit avec fonctions réservées au Plex Pass |
| Compte en ligne pour le serveur | Non | Oui |
| Transcodage matériel | Inclus | Réservé au Plex Pass |
| Code source | Libre (GPL) | Propriétaire |
| Applications TV | Officielles sur les grandes plateformes | Officielles, plus abouties |
| Configuration initiale | À faire soi-même | Largement automatisée |
Le transcodage matériel est le point de bascule le plus concret : Plex le facture, Jellyfin le fournit. C’est aussi ce qui rend la suite de ce guide indispensable, puisque personne ne le configurera à votre place.
Les conditions d’accès distant de Plex ont évolué récemment. Vérifiez-les sur le site de l’éditeur avant de comparer : elles ne sont plus celles que décrivent la plupart des articles.
Prérequis : quelle machine pour Jellyfin ?
Le processeur, et surtout son circuit graphique
Jellyfin lit vos fichiers tels quels quand l’appareil du salon sait les décoder. Il les convertit à la volée dans le cas contraire : c’est le transcodage, et c’est la seule opération réellement coûteuse.
En logiciel, un flux 4K HEVC occupe un processeur récent à lui seul. En matériel, le même flux est pris en charge par le circuit vidéo dédié du GPU, et le processeur reste disponible. Un Intel doté d’un circuit graphique intégré récent suffit largement pour deux à trois flux simultanés.
Tout se joue donc sur une seule question, posée pour chaque lecture : l’appareil sait-il décoder ce fichier ? Si oui, votre serveur ne fait presque rien. Si non, il travaille et c’est le transcodage matériel qui décide s’il travaille bien ou mal.
Stockage et mémoire
Comptez 2 Go de RAM pour un usage familial, 4 Go si plusieurs personnes regardent en même temps. Prévoyez un espace séparé pour le cache de transcodage : il grossit vite et se remplit sans prévenir.
Si vos fichiers vivent déjà sur une machine dédiée, l’installation de TrueNAS pour monter un NAS maison vous donne le socle de stockage sur lequel poser Jellyfin.
Choisir sa voie d’installation
L’arbitrage est plus simple qu’il n’y paraît : la documentation officielle ne fournit un dépôt natif que pour Debian, Ubuntu et leurs dérivés. Pour toutes les autres distributions, elle écrit que les conteneurs constituent la méthode recommandée.
| Dépôt APT | Conteneur Docker | |
|---|---|---|
| Distributions | Debian, Ubuntu, Mint, Raspberry Pi OS, KDE Neon | Toutes |
| Mise à jour | Avec le système | En changeant l’image |
| Transcodage matériel | Configuration directe | Devices à monter explicitement |
| Isolation | Aucune | Complète |
| Retour en arrière | Difficile | Immédiat |
Si vous êtes sur Debian ou Ubuntu et que Jellyfin est le seul service de la machine, prenez le dépôt APT. Dans tous les autres cas, prenez le conteneur.
Installer Jellyfin sur Debian et Ubuntu
Le projet fournit un script qui ajoute le dépôt et installe le serveur. Il le distribue avec sa somme de contrôle : vérifiez-la. C’est votre seule protection contre un script altéré en transit, et elle disparaît dès qu’on envoie le téléchargement directement dans bash sans jamais le lire — une pratique courante dans les guides d’installation.
# Télécharger le script et sa somme de contrôle
curl -s https://repo.jellyfin.org/install-debuntu.sh -O
curl -s https://repo.jellyfin.org/install-debuntu.sh.sha256sum -O
# Vérifier l'intégrité avant toute exécution
sha256sum -c install-debuntu.sh.sha256sum
La sortie doit se terminer par Réussi ou OK. Si la vérification échoue, n’exécutez pas le script : retéléchargez les deux fichiers.
La documentation invite ensuite à lire le script avant de l’exécuter. Prenez ces trente secondes : vous saurez quel dépôt sera ajouté à votre système.
# Lire le script avant de l'exécuter (q pour quitter)
less install-debuntu.sh
# Installer Jellyfin
sudo bash install-debuntu.sh
Le script gère Debian, Ubuntu et les dérivés courants — la documentation cite Linux Mint, Raspberry Pi OS et KDE Neon.
Vérifier que l’étape a réussi :
systemctl status jellyfin
Le service doit apparaître active (running). Ouvrez ensuite http://ADRESSE_IP:8096 depuis un navigateur du réseau local.
Fedora, Arch, openSUSE : ce que dit vraiment la documentation
La documentation officielle n’ouvre aucune section d’installation native pour ces distributions. Elle mentionne des paquets maintenus par la communauté et renvoie vers les conteneurs comme méthode recommandée.
Concrètement : un paquet existe peut-être dans vos dépôts ou sur AUR, mais il n’est pas maintenu par le projet, et vous serez seul en cas de régression. Vérifiez ce que propose votre distribution avant de choisir :
# Fedora
dnf search jellyfin
# Arch et dérivés
pacman -Ss jellyfin
# openSUSE
zypper search jellyfin
Si le résultat vous laisse un doute, passez au conteneur.
Installer Jellyfin avec Docker Compose
Cette voie fonctionne sur toutes les distributions et rend le retour en arrière trivial. Elle suppose Docker installé : si ce n’est pas fait, suivez d’abord le guide d’installation de Docker sur Linux.
Créez d’abord l’arborescence et donnez-la au compte qui fera tourner Jellyfin. Ne sautez pas cette étape : si les dossiers n’existent pas, Docker les crée lui-même en root, Jellyfin ne peut plus y écrire, et le conteneur redémarre en boucle avec une erreur Access to the path '/config' is denied.
# Adaptez 1000:1000 au compte qui possédera les données (voir plus bas)
sudo mkdir -p /srv/jellyfin/config /srv/jellyfin/cache
sudo chown -R 1000:1000 /srv/jellyfin
Voici ensuite le fichier compose.yaml officiel, adapté avec des chemins concrets :
services:
jellyfin:
image: jellyfin/jellyfin:10.11.11
container_name: jellyfin
user: 1000:1000
ports:
- 8096:8096/tcp
- 7359:7359/udp
volumes:
- /srv/jellyfin/config:/config
- /srv/jellyfin/cache:/cache
- type: bind
source: /srv/media
target: /media
restart: 'unless-stopped'
environment:
- JELLYFIN_PublishedServerUrl=http://192.168.1.50
extra_hosts:
- 'host.docker.internal:host-gateway'
Quatre points méritent une explication.
L’image est épinglée sur une version plutôt que sur latest. Une mise à jour d’image ne se déclenchera alors jamais toute seule au redémarrage du conteneur, ce qui vous évite de découvrir une régression un dimanche soir.
Le port 7359/udp sert à la découverte automatique du serveur par les applications clientes sur le réseau local. Sans lui, il faudra saisir l’adresse à la main sur chaque appareil.
JELLYFIN_PublishedServerUrl indique au serveur l’adresse par laquelle les clients doivent le joindre. Mettez-y l’adresse IP de la machine, ou votre nom de domaine si vous passez par un reverse proxy.
Le mode réseau reste bridge, la valeur par défaut de Docker. La documentation précise que le mode host est optionnel et n’est requis que pour le DLNA. Ne l’activez pas sans raison : il supprime l’isolation réseau du conteneur.
Démarrez :
docker compose up -d
Vérifier que l’étape a réussi :
docker compose ps
docker compose logs --tail=30 jellyfin
Le conteneur doit être running, et les journaux se terminer sans erreur de permission.
Les permissions des dossiers média : l’étape où tout casse
C’est le premier écueil, et son symptôme trompe : le conteneur démarre, l’interface s’affiche, mais la bibliothèque reste vide ou refuse de lire les fichiers.
La ligne user: 1000:1000 fait tourner Jellyfin sous cet identifiant, qui doit pouvoir lire vos fichiers sur l’hôte. Relevez le vôtre :
id -u
id -g
Reportez ces deux valeurs dans le fichier compose, puis vérifiez que le dossier média est bien accessible à ce compte :
ls -l /srv/media
PUIDetPGIDn’existent pas dans l’image officielleLes variables
PUIDetPGIDsont une convention propre aux images de LinuxServer.io, que reprennent beaucoup de fichiers compose partagés en ligne. Sur l’image officiellejellyfin/jellyfin, les ajouter n’a aucun effet : le conteneur continue de tourner sous l’utilisateur par défaut, et vos permissions ne correspondent à rien.Sur l’image officielle, le réglage se fait avec la clé
user:, et l’accès au GPU avecgroup_add:. Si vous partez d’un fichier compose trouvé en ligne, c’est le premier point à corriger.
La documentation formule la règle ainsi : remplacez uid:gid pour exécuter Jellyfin sous un utilisateur ou un groupe précis, et retirez entièrement l’argument user pour conserver l’utilisateur par défaut.
Premier démarrage : assistant, bibliothèques et adresse du serveur
À la première ouverture de http://ADRESSE_IP:8096, un assistant demande la langue, un compte administrateur, puis vos bibliothèques.
L’adresse du serveur, que les applications clientes réclament, est simplement http://ADRESSE_IP:8096 sur le réseau local. Depuis l’extérieur, ce sera l’adresse mise en place plus loin dans ce guide — jamais votre adresse IP publique suivie du port.
La reconnaissance automatique des films et séries dépend entièrement du nommage des fichiers. Une arborescence lisible évite des heures de correction manuelle :
/srv/media/
├── Films/
│ └── Le Nom du Film (2019)/
│ └── Le Nom du Film (2019).mkv
└── Series/
└── Nom de la Serie/
└── Saison 01/
└── Nom de la Serie S01E01.mkv
L’année entre parenthèses et le format S01E01 sont les deux éléments qui séparent une fiche complète d’un fichier non identifié.
Activer le transcodage matériel (VA-API, QSV, NVENC)
C’est la section qui sépare un serveur confortable d’un serveur qui rame. Elle couvre ici les trois fabricants, Intel, NVIDIA et AMD.
La documentation valide six méthodes d’accélération : Intel Quick Sync Video (QSV), NVIDIA NVDEC/NVENC, AMD Advanced Media Framework (AMF), Intel/AMD Video Acceleration API (VA-API, Linux uniquement), Apple Video Toolbox (macOS uniquement) et Rockchip RKMPP (Linux uniquement).
Sous Linux, cela laisse quatre options réelles : VA-API, QSV, NVENC, et RKMPP sur les cartes Rockchip — celles des Orange Pi et de plusieurs mini-PC ARM.
Un préalable qui invalide tout le reste s’il n’est pas respecté : n’utilisez que jellyfin-ffmpeg, reconnaissable au suffixe -Jellyfin dans sa chaîne de version. La documentation avertit qu’un binaire FFmpeg récupéré ailleurs ne donne qu’une accélération partielle. C’est une cause fréquente de transcodage qui « ne marche qu’à moitié » sans message d’erreur.
Identifier son circuit graphique et son device
# Lister les périphériques de rendu disponibles
ls -l /dev/dri/
# Identifier le GPU
lspci | grep -Ei 'vga|3d|display'
Vous devez voir au moins un renderD128. S’il est absent, aucune accélération matérielle ne sera possible : le noyau ne voit pas de circuit graphique exploitable. Sur une machine à deux GPU, renderD129 correspond au second.
Intel : QSV et VA-API en conteneur
L’image officielle Jellyfin embarque déjà les pilotes Intel en mode utilisateur et l’exécution OpenCL. Vous n’avez rien à installer dans le conteneur, seulement à lui donner accès au matériel.
Relevez l’identifiant du groupe render de l’hôte :
getent group render | cut -d: -f3
Reportez cette valeur — dans l’exemple ci-dessous, 110 — puis ajoutez ces deux clés au service jellyfin du fichier créé plus haut. Ce n’est pas un fichier de remplacement : conservez ports:, container_name:, restart: et le reste, sans quoi plus aucun port ne sera publié et l’interface deviendra injoignable.
group_add:
- '110'
devices:
- /dev/dri/renderD128:/dev/dri/renderD128
Recréez le conteneur avec docker compose up -d, puis activez l’accélération dans les réglages de transcodage du tableau de bord, en choisissant VA-API ou QSV.
L’identifiant du groupe render peut changer d’une distribution à l’autre, et après certaines mises à jour. Relevez-le toujours plutôt que de recopier une valeur trouvée en ligne : un group_add erroné produit exactement le même symptôme qu’une absence de configuration.
NVIDIA : NVENC
Deux prérequis sur l’hôte, dans cet ordre. D’abord un pilote propriétaire à jour : la documentation exige la version 520.56.06 minimum pour Jellyfin 10.11. Notre guide d’installation du driver NVIDIA sous Linux couvre la procédure par distribution. Ensuite le NVIDIA Container Toolkit, qui donne à Docker l’accès au GPU.
# Vérifier la version du pilote installé
nvidia-smi --query-gpu=driver_version --format=csv,noheader
Là encore, ces clés s’ajoutent au service jellyfin du fichier créé plus haut, elles ne le remplacent pas :
runtime: nvidia
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
Les variables NVIDIA_VISIBLE_DEVICES et NVIDIA_DRIVER_CAPABILITIES sont déjà définies dans l’image officielle : ne les ajoutez pas.
AMD
La documentation est explicite : sous Linux, VA-API est la méthode préférée sur tous les GPU AMD, avec une accélération complète à partir des cartes Polaris (RX 400 et RX 500) et plus récentes. AMF n’est pas recommandé sous Linux.
Sur Debian et Ubuntu, le paquet jellyfin-ffmpeg7 embarque les pilotes Mesa en mode utilisateur. En installation par paquet, ajoutez l’utilisateur système aux groupes qui donnent accès au GPU :
sudo usermod -aG render,video jellyfin
sudo systemctl restart jellyfin
Sur Arch, installez libva-mesa-driver et vulkan-radeon. En conteneur, la configuration est celle de la section Intel : /dev/dri/renderD128 et le groupe render.
Une limite à connaître : la documentation indique qu’il n’existe aucun moyen fiable de lire la charge des moteurs VCE, UVD et VCN d’un GPU AMD sous Linux. Elle suggère de se rabattre sur la lecture des autres moteurs avec l’outil radeontop. Le comportement dépend par ailleurs des versions du noyau et du firmware.
# Debian et Ubuntu
sudo apt install radeontop
sudo radeontop
Sur AMD, croisez donc radeontop avec le contrôle par la charge processeur décrit à la section suivante : aucun des deux ne suffit seul.
Vérifier que le transcodage matériel est réellement actif
C’est l’étape que tous les tutoriels omettent, alors qu’une configuration acceptée par l’interface peut parfaitement retomber en logiciel sans le dire. Trois contrôles, du plus simple au plus précis.
1. Le tableau de bord. Lancez la lecture d’un fichier qui force la conversion — un fichier 4K HEVC sur un client qui ne le décode pas — puis ouvrez le tableau de bord. La documentation indique que « le type utilisé sera indiqué dans le tableau de bord pendant la lecture d’un fichier ».
2. La charge processeur. C’est le contrôle le plus concluant. Pendant cette même lecture, depuis l’hôte :
# Combien de cœurs, puis les processus les plus consommateurs
nproc
ps -eo pcpu,pid,comm --sort=-pcpu | head -6
Cherchez la ligne ffmpeg, et lisez son pourcentage en gardant une chose en tête : ps additionne les threads, si bien qu’un processus peut dépasser 100 %. Le plafond n’est pas 100 mais 100 × le nombre de cœurs.
Un encodage logiciel est massivement parallélisé : sur un quatre cœurs, il affichera plusieurs centaines de pour cent, souvent 300 à 400. C’est le signe que le transcodage est resté logiciel. Avec l’accélération matérielle active, ffmpeg retombe à quelques dizaines de pour cent, le GPU faisant le travail.
3. Le device vu depuis le conteneur. Si les deux premiers contrôles sont mauvais, vérifiez d’abord que le GPU est bien visible à l’intérieur :
docker exec jellyfin ls -l /dev/dri
Une réponse No such file or directory signifie que la clé devices: n’a pas été prise en compte — vous avez probablement modifié le fichier compose sans recréer le conteneur.
En cas de doute persistant, la documentation renvoie vers les journaux de FFmpeg : « If media is unable to transcode, first check the ffmpeg logs. »
Leur emplacement demande une précision que la plupart des guides escamotent, et une mise en garde.
La documentation décrit les chemins par défaut : le dossier de journaux est <répertoire de données>/log, le répertoire de données valant $XDG_DATA_HOME/jellyfin s’il est défini, sinon $HOME/.local/share/jellyfin. Ces valeurs ne s’appliquent pas à une installation par paquet. Le paquet Debian fait tourner le service sous un compte système dédié et fixe les chemins dans /etc/default/jellyfin :
| Variable | Valeur posée par le paquet |
|---|---|
JELLYFIN_LOG_DIR |
/var/log/jellyfin |
JELLYFIN_DATA_DIR |
/var/lib/jellyfin |
JELLYFIN_CONFIG_DIR |
/etc/jellyfin |
JELLYFIN_CACHE_DIR |
/var/cache/jellyfin |
Vos journaux sont donc dans /var/log/jellyfin. Pour le vérifier sur votre machine plutôt que de me croire :
# Installation par paquet : lire les valeurs réellement chargées
grep JELLYFIN_LOG_DIR /etc/default/jellyfin
sudo ls /var/log/jellyfin
# Conteneur
docker exec jellyfin ls /config/log
Une précision qui fait perdre du temps à beaucoup de monde : systemctl show jellyfin -p Environment ne renvoie rien ici. L’unité Jellyfin déclare un EnvironmentFile, et systemd n’expose dans cette propriété que les directives Environment=. Utilisez systemctl show jellyfin -p EnvironmentFiles si vous voulez retrouver le chemin du fichier.
HDR : convertir sans écrouler le serveur
Un fichier HDR lu sur un écran qui ne gère pas le HDR doit être converti en SDR. Cette opération, le tone mapping, est nettement plus coûteuse qu’un transcodage ordinaire : c’est elle qui explique la plupart des saccades sur des fichiers 4K qui passaient très bien en 1080p.
Sur Intel, la documentation décrit deux méthodes, et le choix n’est pas anodin.
| Méthode | Avantages | Limites |
|---|---|---|
| OpenCL | Gère le Dolby Vision profil 5, réglages fins détaillés, matériel largement compatible | Exécution OpenCL parfois à installer à la main sous Linux |
| QSV VPP | Consommation plus faible, s’appuie sur le circuit dédié Intel | Réglages pauvres, peu de modèles de GPU compatibles, disponible uniquement sous Linux |
La documentation précise que le tone mapping HDR et Dolby Vision vers SDR accéléré matériellement est pris en charge sur tous les GPU Intel capables de décoder le HEVC 10 bits. Pour la voie OpenCL, l’exécution doit parfois être installée manuellement : le paquet est intel-opencl-icd, et les versions 23.xx.xxxxx ou plus récentes sont recommandées sur les processeurs récents.
Prenez OpenCL si vous avez du Dolby Vision dans votre médiathèque, QSV VPP si vous cherchez la consommation la plus basse et que votre GPU figure parmi les modèles compatibles.
Accéder à Jellyfin depuis l’extérieur
Avertissement
N’ouvrez jamais le port 8096 sur votre box pour accéder à Jellyfin depuis Internet. Le trafic circulerait en clair, mot de passe compris, et exposerait directement votre serveur. Les deux méthodes ci-dessous règlent le problème.
Un VPN maillé : la voie la plus sûre
C’est la solution à privilégier pour un usage familial. Vos appareils rejoignent un réseau privé et joignent Jellyfin comme s’ils étaient à la maison, sans aucun port ouvert sur votre box. La configuration de Tailscale sous Linux prend quelques minutes et fonctionne aussi sur Android et iOS.
Sa limite : chaque appareil doit installer le client VPN. C’est rédhibitoire pour une TV connectée, et pour partager l’accès avec quelqu’un d’extérieur.
Un reverse proxy avec HTTPS
Pour une adresse publique consultable depuis n’importe quel appareil, il faut un reverse proxy qui termine le HTTPS devant Jellyfin. La mise en place d’un reverse proxy avec Nginx Proxy Manager couvre la génération automatique du certificat.
Deux réglages à ne pas oublier : renseigner votre nom de domaine dans JELLYFIN_PublishedServerUrl, et n’exposer que le proxy — le port 8096 reste sur le réseau local.
Regarder Jellyfin sur sa TV
Jellyfin publie des applications sur la plupart des plateformes du salon. Toutes sont libres, à une exception près.
| Plateforme | Application | Statut |
|---|---|---|
| Android TV, Fire TV | Jellyfin pour Android TV | Officielle |
| Samsung (Tizen) | Jellyfin | Officielle |
| LG (webOS) | Jellyfin | Officielle |
| Roku | Jellyfin | Officielle |
| Xbox | Jellyfin | Officielle |
| Android | Jellyfin pour Android | Officielle |
| iOS, iPadOS | Jellyfin pour iOS | Officielle |
| iOS, iPadOS, Apple TV | Swiftfin | Officielle, en bêta |
| Windows, macOS, Linux | Jellyfin Media Player | Officielle |
| Kodi | JellyCon | Extension officielle |
| iOS, iPadOS, tvOS | Infuse | Tierce, propriétaire |
Trois précisions avant de choisir.
Sur Apple TV, l’application du projet s’appelle Swiftfin. Jellyfin l’a présentée comme son application native iOS, iPadOS et tvOS, fonctionnant à partir de la version 15 de ces systèmes, et la page des clients l’étiquette officielle en bêta. Deux réserves, donc : son statut de bêta, et le fait qu’elle soit limitée à la vidéo — ni musique, ni livres audio, ni photos. Pour ces contenus, il vous faudra une autre application. Infuse, client tiers propriétaire, reste l’alternative la plus citée sur ces mêmes appareils.
Sur les TV Samsung et LG, les applications officielles existent, mais le décodage dépend du matériel de la TV. Une TV d’entrée de gamme obligera votre serveur à transcoder en permanence : c’est exactement le cas où le transcodage matériel devient indispensable.
Sur un NAS Synology, Jellyfin s’installe en conteneur via Container Manager, avec le même fichier compose que ci-dessus. Le transcodage matériel n’y est possible que sur les modèles dotés d’un processeur Intel avec circuit graphique intégré : vérifiez la présence de /dev/dri sur votre NAS avant d’espérer l’activer.
Mettre à jour, sauvegarder et désinstaller
Sauvegardez toujours le dossier de configuration avant une mise à jour. C’est lui qui contient vos comptes, vos bibliothèques et vos réglages.
# Conteneur : sauvegarde du dossier de configuration
sudo tar czf jellyfin-config-$(date +%F).tar.gz /srv/jellyfin/config
Mise à jour selon la voie d’installation :
# Dépôt APT
sudo apt update
sudo apt install --only-upgrade jellyfin jellyfin-server jellyfin-web
# Conteneur : modifiez le numéro de version dans compose.yaml, puis
docker compose pull && docker compose up -d
N’utilisez pas
apt upgrade jellyfinContrairement à ce que la syntaxe laisse croire,
apt upgradesuivi d’un nom de paquet ne met pas à jour ce seul paquet : il déclenche une mise à jour de tout le système, en s’assurant simplement que celui-ci en fait partie. Sur une machine qui n’a pas été mise à jour depuis longtemps, vous récupérez des dizaines de paquets sans l’avoir demandé. La forme qui ne touche que ce que vous visez estapt install --only-upgrade.
Désinstallation. Les noms de paquets varient selon ce que le script a installé sur votre système : listez-les d’abord plutôt que de les deviner.
# Lister les paquets Jellyfin présents sur le système
dpkg -l 'jellyfin*' | awk '/^(ii|rc)/ {print $2}'
# Les retirer avec leur configuration
sudo apt purge $(dpkg -l 'jellyfin*' | awk '/^(ii|rc)/ {print $2}')
Le motif ^(ii|rc) n’est pas une coquetterie : ii désigne un paquet installé, rc un paquet déjà retiré dont la configuration traîne encore. Si vous aviez fait un apt remove auparavant, ne filtrer que sur ii laisserait ces fichiers en place — exactement ce qu’on cherche à éviter ici.
# Conteneur : arrete et supprime le conteneur
docker compose down
Un mot sur la première commande : apt purge échoue en bloc si un seul des noms que vous lui passez n’existe pas, et ne retire alors rien du tout. Construire la liste depuis dpkg évite ce piège.
Avertissement
docker compose downn’efface pas vos dossiersconfig,cacheetmedia, qui vivent sur l’hôte. Pour repartir de zéro, supprimez/srv/jellyfinmanuellement — et seulement celui-ci. Relisez le chemin avant de valider : une erreur de frappe dans une suppression récursive ne se rattrape pas.
Erreurs courantes
Jellyfin ne se lance pas, la page ne s’ouvre pas
Commencez par déterminer si le serveur tourne, avant de soupçonner le réseau. En installation par paquet, systemctl status jellyfin doit afficher active (running) ; s’il affiche failed, sudo journalctl -u jellyfin -n 50 donne la raison. En conteneur, docker compose ps doit afficher running : un conteneur qui redémarre en boucle signale presque toujours un problème de droits sur /srv/jellyfin, corrigé par le chown de la section installation.
Si le service tourne mais que la page reste inaccessible, vérifiez dans l’ordre que le port 8096 est bien publié (docker compose ps doit montrer 0.0.0.0:8096->8096/tcp), puis que le pare-feu de l’hôte le laisse passer.
La bibliothèque reste vide après l’analyse
Neuf fois sur dix, c’est un problème de permissions et non de nommage. Le compte sous lequel tourne Jellyfin ne peut pas lire le dossier. Vérifiez que l’identifiant de la clé user: correspond à un compte ayant accès à /srv/media. Si vous êtes parti d’un fichier compose trouvé en ligne, relisez l’encadré sur PUID et PGID.
Les applications clientes ne trouvent pas le serveur
La découverte automatique passe par le port 7359 en UDP. S’il n’est pas publié dans votre fichier compose, aucune application ne verra le serveur toute seule. Saisissez alors l’adresse manuellement : http://ADRESSE_IP:8096.
Si la connexion échoue aussi en manuel, vérifiez que le pare-feu de l’hôte laisse passer le port 8096 depuis votre réseau local.
« Access denied » ou impossible de se connecter depuis l’extérieur
Ce message vient presque toujours d’un accès distant tenté sans passer par le VPN ou le reverse proxy. Vérifiez que JELLYFIN_PublishedServerUrl contient bien l’adresse par laquelle le client arrive : si le serveur annonce une adresse locale à un client distant, la connexion s’établit puis échoue à la lecture.
Le transcodage reste logiciel malgré la configuration
Quatre causes, à écarter dans cet ordre. Le device /dev/dri/renderD128 n’est pas monté dans le conteneur. Le groupe render n’a pas été ajouté avec group_add, ou son identifiant a changé. Le binaire FFmpeg utilisé n’est pas jellyfin-ffmpeg — le suffixe -Jellyfin doit apparaître dans sa version. Enfin, le format source n’est peut-être pas pris en charge par votre circuit graphique : un codec AV1 sur un GPU ancien retombera toujours en logiciel.
La lecture 4K saccade alors que le 1080p passe
Regardez d’abord si le fichier est en HDR. La conversion HDR vers SDR est bien plus lourde qu’un transcodage classique, et c’est la cause la plus fréquente de ce symptôme précis. Reportez-vous à la section sur le tone mapping. Si le fichier n’est pas HDR, le débit du réseau est le second suspect : un flux 4K non transcodé demande une liaison stable, et le Wi-Fi d’entrée de gamme n’y suffit pas toujours.
Questions fréquentes
Jellyfin est-il vraiment gratuit ?
Oui, intégralement. Aucune fonction n’est réservée à un abonnement, y compris le transcodage matériel, qui est réservé aux abonnés Plex Pass chez Plex. Le projet est libre et financé par des dons.
Quel serveur faut-il pour faire tourner Jellyfin ?
Un mini-PC équipé d’un processeur Intel récent avec circuit graphique intégré et 4 Go de RAM couvre confortablement un usage familial. Un Raspberry Pi convient pour de la lecture directe, mais atteint vite ses limites dès qu’il faut transcoder.
Quelle est l’adresse de mon serveur Jellyfin ?
Sur le réseau local, http://ADRESSE_IP:8096, où l’adresse IP est celle de la machine qui héberge Jellyfin. Depuis l’extérieur, c’est l’adresse de votre VPN maillé ou le nom de domaine de votre reverse proxy — jamais votre adresse IP publique suivie du port.
Un GPU est-il obligatoire ?
Non. Si tous vos appareils lisent vos fichiers sans conversion, le processeur n’intervient presque pas. Le GPU devient indispensable dès qu’un appareil impose un transcodage, ce qui arrive vite avec une TV ancienne ou une connexion limitée.
Pourquoi Jellyfin consomme-t-il autant de processeur ?
Parce qu’il transcode en logiciel. Soit l’accélération matérielle n’est pas activée, soit elle est configurée mais inopérante — le device n’est pas monté, le groupe render est absent, ou le binaire FFmpeg n’est pas celui du projet. La section sur la vérification donne les trois contrôles qui tranchent.
Faut-il l’image officielle ou celle de LinuxServer.io ?
Les deux fonctionnent, mais elles ne se configurent pas pareil. L’image officielle utilise user: et group_add: ; celle de LinuxServer.io utilise PUID, PGID et ses propres modules. Choisissez-en une et tenez-vous-y : mélanger les deux conventions est la cause d’échec la plus fréquente.
Jellyfin est-il légal ?
Le logiciel l’est entièrement : c’est un lecteur et un organisateur de fichiers, publié sous licence libre. La légalité dépend uniquement des fichiers que vous y déposez, exactement comme pour un lecteur vidéo classique.
Quels plugins installer en premier ?
Les plugins de métadonnées sont les seuls réellement utiles au départ, pour compléter les fiches de films et séries. Installez-les depuis Tableau de bord → Plugins, et n’en ajoutez pas d’autres avant d’en avoir un besoin précis : chacun ajoute une surface de maintenance.
Conclusion
Sur Debian ou Ubuntu, prenez le dépôt APT et vérifiez la somme de contrôle du script avant de l’exécuter. Partout ailleurs, prenez le conteneur : c’est la voie que le projet recommande lui-même hors de la famille Debian. Dans les deux cas, partez de l’image officielle et de ses conventions user: et group_add: — c’est ce qui vous évitera le piège PUID/PGID sur lequel bute la majorité des installations.
La configuration qui change tout reste le transcodage matériel, et la seule façon de savoir s’il fonctionne est de lancer une lecture exigeante en surveillant la charge processeur. Ne vous fiez pas à l’interface qui accepte votre réglage : elle ne vous dira pas qu’il est resté sans effet.
Pour l’accès distant, commencez par le VPN maillé : plus rapide à mettre en place qu’un reverse proxy, et sans aucun port ouvert. Vous basculerez vers le reverse proxy avec Nginx Proxy Manager le jour où vous voudrez partager l’accès avec quelqu’un d’extérieur. Et si votre médiathèque n’a pas encore de logement stable, le NAS maison sous TrueNAS est le socle à poser avant tout le reste.
