Automatisez la gestion de vos médias Jellyfin avec Jellysweep

Jimmy

28 oct. 2026 — 9 min read

Dans le précédent article de la série des outils pouvant accompagner un serveur Jellyfin, nous vous avons présenté et montré comment installer et utiliser Jellystat, un outil permettant de récolter des statistiques de visionnages des médias sur un serveur Jellyfin.

Jellystat peut être également accompagné de l'outil Jellysweep : Un outil se basant sur les statistiques récoltées par Jellystat afin de nettoyer automatiquement les médias les moins visionnés, permettant d'optimiser l'espace de stockage disponible.

Comme les précédents outils liés à Jellyfin, la méthode recommandée pour installer Jellysweep est d'utiliser Docker Compose, voici comment procéder à l'installation :

Comment installer Jellysweep

Prérequis

Pour suivre ce tutoriel d'installation, il vous faut installer Docker et Docker Compose sur votre appareil. Vous pouvez découvrir comment procéder dans les articles ci-dessous :

Sur Linux Debian :

Sur Windows :

Installation avec Docker Compose

Pour installer Jellysweep, il suffit de créer un fichier docker-compose.yml dans un répertoire dédié à l'outil. Dans ce fichier, ajoutez le contenu suivant :

services:
  jellysweep:
    image: ghcr.io/jon4hz/jellysweep:latest
    container_name: jellysweep
    restart: unless-stopped
    ports:
      - "3002:3002"
    volumes:
      - ./config.yml:/app/config.yml:ro # use config file or env vars
      - ./data:/app/data
      # Mount Jellyfin library paths at the same locations for disk usage monitoring
      # Example: if Jellyfin has /data/movies, mount it the same way here
      - /chemin/vers/vos/medias/:/media/:ro
    environment:
      # You can also override config options with env vars
      - JELLYSWEEP_DRY_RUN=false
      - JELLYSWEEP_LISTEN=0.0.0.0:3002
    # enable debug logs (choose one approach):
    # via environment variable:
    # environment:
    #   - JELLYSWEEP_LOG_LEVEL=debug
    # via command flag:
    # command:
    #   - serve
    #   - --log-level=debug

Ce fichier doit être accompagné d'un second fichier appelé config.yml qui va vous permettre de configurer Jellysweep, c'est l'étape la plus pointue de l'installation.

Configuration de Jellysweep

Fichier config.yml

Le fichier se présente comme ci-dessous, chaque section permet de configurer une option de l'outil.

log_level: "info"                # Log verbosity: "debug", "info", "warn", "error"
dry_run: true                    # Set to true for testing
listen: "0.0.0.0:3002"           # Web interface address and port
cleanup_schedule: "0 */12 * * *" # Every 12 hours
cleanup_mode: "keep_seasons"     # Cleanup mode: "all", "keep_episodes", or "keep_seasons"
keep_count: 1                    # Number of episodes/seasons to keep (when using keep_episodes or keep_seasons)
api_key: ""                      # Optional: API key for Jellyfin plugin integration
session_key: "clé à générer"  # Random string for session encryption
session_max_age: 172800          # Session max age in seconds (48 hours)
secure_cookies: false             # Set Secure flag on session cookies (disable only for local development)
# trusted_proxies:               # Optional: list of trusted reverse-proxy IPs/CIDRs
#   - "10.0.0.1"                 # If unset, all proxies are trusted
#   - "192.168.1.0/24"
server_url: "http://<ip_de_jellysweep>:3002"

# Database configuration (optional)
database:
  type: "sqlite"
  path: "./data/jellysweep.db"

# Authentication (optional - if no auth is configured, web interface is accessible without authentication)
auth:
  # Jellyfin Authentication
  jellyfin:
    enabled: true                      # Default authentication method

# Jellyfin server configuration
jellyfin:
  url: "http://ip_de_jellyfin"         # Your Jellyfin server URL
  api_key: "clé à créer dans le dashboard jellyfin"     # Jellyfin API key

leaving_collections_enabled: true      # Create collections for media scheduled for deletion
leaving_collections_movie_name: "Leaving Movies"
leaving_collections_tv_name: "Leaving TV Shows"

# Library-specific settings
libraries:

  # Name must match the Library name in Jellyfin
  "Films":
    enabled: true
    cleanup_delay: 60
    protection_period: 90         # Protect requested content for 90 days
    # Filter configuration
    filter:
      content_age_threshold: 120        # Content must be at least 120 days old
      last_stream_threshold: 90         # Last watched at least 90 days ago
      content_size_threshold: 1073741824  # 1GB minimum (0 = no minimum)
      tunarr_enabled: false              # Protect items used by Tunarr channels (requires tunarr config)
      exclude_tags:
        - "jellysweep-exclude"
        - "keep"
        - "favorites"
    # Disk usage-based cleanup for movies
    disk_usage_thresholds:
      - usage_percent: 70.0       # When disk usage reaches 70%
        max_cleanup_delay: 30     # Reduce grace period to 30 days
      - usage_percent: 85.0       # When disk usage reaches 85%
        max_cleanup_delay: 14      # Reduce grace period to 14 days
      - usage_percent: 90.0       # When disk usage reaches 90%
        max_cleanup_delay: 7      # Reduce grace period to 7 days
      - usage_percent: 95.0       # When disk usage reaches 95%
        max_cleanup_delay: 2      # Reduce grace period to 2 days

  "Séries":
    enabled: true
    cleanup_delay: 60
    protection_period: 90
    # Filter configuration
    filter:
      content_age_threshold: 120
      last_stream_threshold: 90
      content_size_threshold: 2147483648  # 2GB minimum
      tunarr_enabled: false             # Disable Tunarr filter for this library
      exclude_tags:
        - "jellysweep-exclude"
        - "ongoing"
        - "keep"
    # Disk usage-based cleanup for TV shows
    disk_usage_thresholds:
      - usage_percent: 70.0
        max_cleanup_delay: 30
      - usage_percent: 85.0
        max_cleanup_delay: 14
      - usage_percent: 90.0
        max_cleanup_delay: 7
      - usage_percent: 95.0
        max_cleanup_delay: 2

# External service integrations
jellyseerr:
  url: "http://<ip_de_seerr>:5055"
  api_key: ""
  timeout: 30                          # HTTP client timeout in seconds (default: 30)

sonarr:
  url: "http://<ip_de_sonarr>:8989"
  api_key: ""
  timeout: 30                          # HTTP client timeout in seconds (default: 30)

radarr:
  url: "http://<ip_de_radarr>:7878"
  api_key: ""
  timeout: 30                          # HTTP client timeout in seconds (default: 30)

jellystat:
  url: "http://<ip_de_jellystat>:3000"
  api_key: ""
  timeout: 30                          # HTTP client timeout in seconds (default: 30)

Voici l'explication des différentes sections à configurer :

Partie fonctionnement du serveur

Les variables les plus importantes à modifier sont celles-ci :

dry_run : IMPORTANT ! Autorise Jellysweep à appliquer les actions de suppression quand la variable est false, ce mode est à désactiver uniquement lorsque l'outil est opérationnel et bien configuré. Il est préférable de désactiver cette option quelques temps après avoir assez de statistiques récoltées par Jellystat.
listen : Indique l'adresse IP sur laquelle le serveur doit être accessible.
cleanup_schedule, cleanup_mode et keep_count : Il s'agit des paramètres de suppression des médias, le premier indique les intervalles de temps auxquelles ces tâches doivent êtres effectuées, le second indique si les séries doivent être supprimées par saisons ou par épisodes, et le dernier indique le nombre de saisons ou épisodes à conserver.
session_key : Il s'agit de la clé de chiffrement permettant de chiffrer les sessions de connexion à l'interface web. Il est recommandé de la générer avec cette commande : openssl rand -base64 32.
server_url : URL à indiquer à partir de laquelle accéder à l'interface web.

Partie authentification et connexion à Jellyfin

La section auth indique à Jellysweep d'utiliser les comptes et identifiants de Jellyfin pour accéder à son interface web, une méthode similaire à Seerr.

La section jellyfin permet de configurer l'accès à votre serveur Jellyfin en indiquant l'URL de ce dernier ainsi qu'une clé API à générer dans son tableau de bord.

Pour créer la clé API nécessaire, il faut vous rendre sur le tableau de bord de votre serveur Jellyfin puis sur la page Clés API.

Il faut ensuite cliquer sur le bouton "Nouvelle clé API", puis attribuer un nom à cette clé. Vous pouvez par exemple entrer le nom du service auquel elle sera destinée, qui est, dans notre cas, Jellysweep.

Vous obtiendrez alors la clé API à entrer dans la variable api_key.

Partie médiathèques

Les variables leaving_collections_enabled, leaving_collections_movie_name et leaving_collections_tv_name permettent de créer et nommer sur Jellyfin des médiathèques dans lesquelles seront rangés les médias qui sont étiquetés par Jellysweep comme étant à supprimer afin de prévenir les utilisateurs des futures suppressions.

Ensuite, la section libraries permet de configurer les paramètres de nettoyage en fonction des différentes médiathèques Jellyfin, les noms des sections des médiathèques doivent êtres identiques à ceux sur Jellyfin (et sont sensibles à la casse).

Ces sections permettent la configuration des conditions avant suppression d'un média, parmi lesquelles se trouvent les conditions suivantes :

Un délai en jours avant la suppression d'un élément noté comme devant être supprimé.
Une période de protection d'un élément que l'on a choisi de ne pas supprimer, avant qu'il puisse être à nouveau étiqueté comme étant à supprimer.
Un nombre de jours minimum pendant lesquels un élément doit être sur Jellyfin avant de pouvoir le supprimer.
Le nombre de jours minimum depuis qu'un élément est visionné avant de pouvoir être supprimé.
La taille minimum que doit faire un élément sur le disque pour pouvoir être supprimé.
Si un élément est mis en favori ou non.
Si un élément possède des étiquettes indiquées permettant d'empêcher sa suppression.
Un délai avant suppression, en jours, selon le pourcentage d'espace disque disponible.

Partie services externes

Cette partie permet de configurer l'accès aux services externes comme Jellystat, Radarr, Sonarr ou encore Seerr, afin d'obtenir des données comme les dates d'ajout des médias dans les médiathèques. Vous pouvez supprimer de la configuration les lignes des services que vous n'utilisez pas.

Pour configurer l'accès à Jellystat, il faut entrer l'URL de ce dernier, ainsi qu'un clé API générée depuis son interface web.

Il faut alors vous rendre sur le tableau de bord de votre serveur Jellystat puis sur la page Paramètres et Clé API.

Et ensuite, attribuer un nom à la clé à créer, puis cliquer sur le bouton "Ajouter une clé". Vous pouvez par exemple entrer le nom du service auquel elle sera destinée, qui est toujours, dans notre cas, Jellysweep.

Vous pouvez désormais trouver la clé nouvellement créée à entrer dans le fichier de configuration de Jellysweep.

Connexion et utilisation de Jellysweep

Une fois configuré, vous pouvez démarrer Jellysweep avec la commande suivante :

docker compose up -d

Vous pouvez désormais accéder à son interface web avec l'URL que vous avez configurée dans le fichier de configuration.

Vous arrivez donc sur la page de connexion, sur laquelle vous pouvez vous connecter avec vos identifiants Jellyfin.

Une fois connecté, vous arrivez sur la page d'accueil du tableau de bord, qui présente les différents médias que Jellysweep prévoit de supprimer avec leur date de suppression.

Si vous avez installé Jellystat peu de temps avant Jellysweep, il est possible que cette page d'accueil ne vous montre aucun élément susceptible d'être supprimé.

Dans l'onglet Stats, vous pouvez alors voir un graphique de l'espace de stockage qui sera libéré lors de la suppression des éléments présentés dans la page d'accueil.

Sur la page d'administration, dans l'onglet "Approval Queue", vous pouvez trouver les éléments que vos utilisateurs ont demandés à garder sur Jellyfin.

Ensuite, dans l'onglet "Keep or Sweep", vous pouvez choisir, en tant qu'administrateur, de conserver un élément pendant la durée de protection configurée (90 jours par défaut), de le conserver indéfiniment ou de le supprimer instantanément.

Puis, dans l'onglet "Users", vous pouvez retrouver les utilisateurs Jellyfin s'étant déjà connectés à Jellysweep, et vous pouvez les autoriser à approuver eux-mêmes leurs demandes de conservation des médias avec le bouton "Enable Auto-Approval".

Sur la page suivante "History", répertorie l'historique des actions effectuées par les utilisateurs, ou bien les actions automatiques de Jellysweep.

Enfin, la page "Scheduler" permet d'afficher les tâches automatiques de Jellysweep et voir la fréquence d'exécution à laquelle elles sont programmées, ainsi que le nombre de fois où les tags Radarr et Sonarr ont été modifiés.

Conclusion

Désormais, avec la suite d'outils Seerr, Jellystat et Jellysweep, vous avez automatisé toutes les étapes de la gestion de vos médias sur Jellyfin. De l'ajout de médias à la demande de vos utilisateurs, jusqu'à la suppression des éléments non visionnés, vous avez à présent un système presque intégralement autonome.

Pour nous aider à nous améliorer, n'hésitez pas à faire part de vos avis en commentaires ou même à poser vos questions si vous avez besoin d'aide supplémentaire.

Notre forum est également accessible afin d'échanger avec nous sur divers sujets :

Forum de Make in Lab

Vous pouvez trouver sur ce forum de l’aide sur le monde informatique, la mise en place de systèmes spécifiques ainsi que du réseau à l’aide de l’équipe de Make in Lab.