---
title: Jellysweep
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, file-management, jellyfin, cleanup, python, automation]
confidence: medium
contested: false
sources: [https://selfh.st/apps/?tag=file-management, https://github.com/jon4hz/jellysweep]
---

# Jellysweep 🧹

> Outil Python d'auto-nettoyage pour **Jellyfin** : supprime automatiquement les films et épisodes non visionnés depuis longtemps, en s'appuyant sur les statistiques de visionnage de votre serveur média.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | https://github.com/jon4hz/jellysweep |
| **GitHub** | https://github.com/jon4hz/jellysweep |
| **License** | MIT |
| **Langage** | Python |
| **Étoiles GitHub** | 13 ⭐ |
| **Dernière MAJ** | 2025 |
| **Catégorie** | [[cat-file-management]] |

## 📝 Description

**Jellysweep** répond à un problème typique des utilisateurs de **Jellyfin** : les bibliothèques gonflent mécaniquement au fil des mois (séries terminées non revisitées, films vus une fois et oubliés, doublons). Plutôt que de purger à la main, Jellysweep automatise la suppression selon des **règles temporelles** et des **statistiques d'usage** fournies par l'API Jellyfin.

Le fonctionnement : Jellysweep interroge l'API Jellyfin, identifie les items (films/épisodes) non joués depuis X jours, vérifie qu'ils ne sont pas dans une « keep list » de l'utilisateur, puis **supprime les fichiers** du filesystem (et du catalogue Jellyfin) après une période de grâce configurable. Possibilité de recevoir une **notification Telegram / Discord / webhook** avant suppression effective.

⚠️ **Note de confiance (low)** : le projet est jeune (13⭐), la dernière MAJ est récente mais la communauté reste limitée. ⚠️ Tester sur un dataset non critique avant déploiement production, et toujours conserver un **backup** des médias.

Idéal pour les utilisateurs de **Sonarr / Radarr / Jellyfin** qui veulent boucler la boucle du cycle : téléchargement → lecture → suppression automatique.

## 🚀 Installation

### Option 1 : Docker Compose (recommandé)

```yaml
version: '3.8'
services:
  jellysweep:
    image: ghcr.io/jon4hz/jellysweep:latest
    container_name: jellysweep
    restart: unless-stopped
    environment:
      - JELLYFIN_URL=http://jellyfin:8096
      - JELLYFIN_API_KEY=***   # Créer dans Jellyfin > Admin > API Keys
      - JELLYFIN_USER_IDS=***_user_id
      - GRACE_PERIOD_DAYS=14
      - UNWATCHED_DAYS_THRESHOLD=90
      - SCAN_CRON=0 3 * * *    # Tous les jours à 3h du matin
      - TZ=Europe/Paris
      - WEBHOOK_URL=***   # Optionnel : notification Telegram/Discord avant suppression
    volumes:
      - /srv/media:/media:ro   # Lecture seule pour l'analyse
      - /srv/media-trash:/trash  # Poubelle avant suppression définitive
    depends_on:
      - jellyfin
    networks:
      - media

  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    restart: unless-stopped
    ports:
      - "8096:8096"
    volumes:
      - /srv/media:/media
      - jellyfin-config:/config
    networks:
      - media

volumes:
  jellyfin-config:

networks:
  media:
    driver: bridge
```

### Option 2 : Installation manuelle

```bash
git clone https://github.com/jon4hz/jellysweep.git
cd jellysweep
pip install -r requirements.txt
cp config.example.yaml config.yaml
# Éditer config.yaml (URL Jellyfin, API key, seuils)
python -m jellysweep --config config.yaml --dry-run
python -m jellysweep --config config.yaml
```

## ⚙️ Configuration

- **API Key Jellyfin** : `Dashboard > Administration > API Keys > +` → nommer « Jellysweep ».
- **Grace period** : nombre de jours entre la détection et la suppression effective (sécurité anti-faux positif).
- **Keep list** : titres à ne jamais supprimer, via fichier `keep.txt` ou interface.
- **Cron interne** : configurer la fréquence d'analyse (1×/jour suffit).
- **Mode dry-run** : **toujours** tester en `--dry-run` d'abord pour voir ce qui serait supprimé.
- **Webhook** : Telegram/Discord pour recevoir la liste des fichiers supprimés la nuit.

## 🔄 Alternatives

### Open Source
- **Sonarr / Radarr** — Gestionnaires automatisés (mais ne suppriment pas l'ancien)
- **cleanup-jellyfin** (scripts) — Projets similaires communautaires
- **trash-guides** (rConfig) — Bonnes pratiques, pas un outil
- [[app-filebrowser]] — Permet la suppression manuelle
- **autoremove-torrents** — Cible qBittorrent/Deluge, pas Jellyfin

### Propriétaires
- Aucune solution propriétaire équivalente. Plex propose des outils similaires côté « managed cloud », mais sans équivalent self-host direct.
- **Plex Pass + Tautulli** — Monitoring Plex (pas Jellyfin), avec quelques règles de cleanup.
- **iDrive / Backblaze B2 lifecycle rules** — Plutôt orienté backup, pas média.

## 🔐 Sécurité

- **HTTPS recommandé** si Jellyfin est exposé (sinon l'API key circule en clair).
- Limiter les permissions de l'API key Jellyfin au strict minimum (lecture + delete).
- **Toujours démarrer en `--dry-run`** et vérifier la liste avant d'activer la suppression réelle.
- **Backup** des médias supprimés : monter un volume `trash` séparé et purger manuellement après 30 jours.
- **Volumes en `:ro`** sur les dossiers médias pour l'analyse (l'app n'écrit que dans `/trash`).
- Surveiller l'espace disque de la poubelle (peut saturer si beaucoup de suppressions).
- **RGPD** : si vos médias contiennent des données personnelles (vidéos de famille), Jellysweep supprime définitivement → adapter la politique de rétention.
- Tester la restauration depuis `/trash` avant de faire confiance à l'outil.

## 📚 Ressources

- [GitHub jon4hz/jellysweep](https://github.com/jon4hz/jellysweep)
- [selfh.st listing](https://selfh.st/apps/?tag=file-management)
- [Reddit - Automating episode cleanup](https://www.reddit.com/r/JellyfinCommunity/comments/1o6ucvu/automating_episode_cleanup/)
- [Jellyfin API docs](https://api.jellyfin.org/)

## Pages Liées
- [[cat-file-management]] — Catégorie File Management
- [[recettes-docker-compose]] — Templates Docker Compose
- [[securisation-home-lab]] — Sécurité
- [[traefik]] — Reverse proxy (si Jellyfin exposé)