Jellysweep

<img src="internal/static/static/jellysweep.png" alt="Jellysweep Logo" width="20%">

Jellysweep is a smart cleanup tool for your Jellyfin media server. It automatically removes old, unwatched movies and TV shows by analyzing your viewing stats and other criteria. It also supports user requests to keep specific content.

[!CAUTION] Always test with dry-run mode first! And review the logs/dashboard to see what jellysweep would've marked for deletion!

---

✨ Key Features

• 🧠 Smart Analytics - Checks jellyseerr for requests and Jellystat/Streamystats for stats
• 🏷️ Tag-Based Control - Leverage your existing Sonarr/Radarr tags to control jellysweep
• 💾 Disk Usage Monitoring - Adaptive cleanup based on disk usage thresholds
• 🧹 Flexible Cleanup Modes - Choose how much of TV Series should be deleted
• 📂 Leaving Collections - Automatically creates Jellyfin collections showing all media scheduled for deletion
• 👥 User Requests - Built-in keep request system for your users
• 🔔 Notifications - Send notifications to users and admins
• 📱 Progressive Web App (PWA) - Install as an app on mobile and desktop
• 🌐 Web Interface - UI to interact with jellysweep

📋 Table of Contents

• Jellysweep
  • ✨ Key Features
  • 📋 Table of Contents
  • 🚀 How It Works
  • 🔍️ Filters
  • 🧹 Cleanup Modes
  • 💾 Disk Usage-Based Cleanup
    • Configuration Example
    • Behavior Examples
  • 📸 Screenshots
    • Dashboard Overview
    • Statistics Dashboard
    • Admin Panel - Keep Requests
    • Admin Panel - Keep or Sweep
    • Scheduler Panel
  • 🔧 Installation
    • Prerequisites
    • Docker Compose
    • Docker Compose with Valkey Cache
  • 🔐 Authentication
    • OIDC/SSO Authentication
    • Jellyfin Authentication
  • 🔔 Web Push Notifications
    • Setup Requirements
  • ⚙️ Configuration
    • Environment Variables
    • Configuration File
  • 🔧 Commands
  • 🤝 Contributing
    • Development Setup
  • 📄 License

🚀 How It Works

Jellysweep looks up your entire media library in jellyfin, sonarr and radarr. Based on different user-defined filers, it then decides which media items are no longer needed and marks them for deletion by adding special tags in sonarr/radarr. Your users can then request to keep specific items via the web interface. Admins can review and approve/decline these requests. Users will receive an email notification, if content that they requested (in jellyseer) is marked for deletion. After a configurable grace period, the media items are then deleted. There is als an option to speed up the deletion process when disk space is running low.

🔍️ Filters

At the core of jellysweep are filters that allow you to define criteria which must be met for a media item to be eligible for deletion. If one of the filters is not met, the item will be skipped and not marked for deletion.

Filters can be configured per library and include:

| Filter | Description | | ------------------------ | -------------------------------------------------------------------------------- | | content_age_threshold | Minimum age of the content in days | | last_stream_threshold | Minimum days since the content was last streamed | | content_size_threshold | Minimum size of the content in bytes (0 = no minimum) | | tunarr_enabled | Whether to protect items used by Tunarr channels (requires Tunarr configuration) | | exclude_tags | List of Sonarr/Radarr tags that exclude content from deletion |

[!IMPORTANT] Once a media item is marked for deletion, it wont go through the filters again. Filter changes will only affect new items that are being considered for deletion.

🧹 Cleanup Modes

Jellysweep supports three different cleanup modes for TV series, configurable globally through the cleanup_mode setting. The mode determines how much content is removed when a series is marked for deletion. Movies are always deleted entirely regardless of the cleanup mode.

The all mode removes the entire series and all its files, providing maximum storage reclamation. This is the default setting.

The keep_episodes mode preserves the first N episodes across all regular seasons while removing everything else. Episodes are counted by their broadcast order, starting from season 1 episode 1, and special episodes in season 0 are always preserved regardless of the count limit.

The keep_seasons mode retains complete early seasons while removing later ones. It keeps the first N lowest-numbered regular seasons. Specials will not be deleted in this mode either.

Both selective modes automatically unmonitor deleted episodes in Sonarr to prevent them from being redownloaded. If a series has less or equal amount of episode as the keep policy requests, the series wont be marked from deletion again.

[!TIP] The selective modes in combination with prefetcharr let you automatically scale your media collection on demand.

💾 Disk Usage-Based Cleanup

Jellysweep monitors disk usage and speeds up cleanup when you're running low on storage. When disk space is tight, it reduces the grace period for deletions while still giving you time to save anything important during normal operation.

[!IMPORTANT] For disk usage monitoring to work in Docker containers, Jellyfin library paths must be mounted at the same locations inside the Jellysweep container. For example, if Jellyfin has /data/movies mapped to /movies, Jellysweep also needs /data/movies mapped to /movies

Configuration Example

libraries:
  "Movies":
    cleanup_delay: 30  # Standard 30-day grace period
    disk_usage_thresholds:
      - usage_percent: 75.0      # When disk usage reaches 75%
        max_cleanup_delay: 14    # Reduce grace period to 14 days
      - usage_percent: 85.0      # When disk usage reaches 85%
        max_cleanup_delay: 7     # Reduce grace period to 7 days
      - usage_percent: 90.0      # When disk usage reaches 90%
        max_cleanup_delay: 3     # Reduce grace period to 3 days

Behavior Examples

Let's say today is 2025-07-26:

• Disk usage 80%: Media gets deleted on 2025-08-25 (after 30 days)
• Disk usage 87%: Media gets deleted on 2025-08-09 (after 14 days)
• Disk usage 93%: Media gets deleted on 2025-08-02 (after 7 days)
• Disk usage 97%: Media gets deleted on 2025-07-29 (after 3 days)

---

📸 Screenshots

Dashboard Overview

<img src="assets/screenshots/dashboard.png" alt="Dashboard Overview" width="75%">

Main dashboard showing media items scheduled for deletion with filtering and search capabilities

Statistics Dashboard

<img src="assets/screenshots/stats.png" alt="Dashboard Statistics" width="75%">

Visual analytics showing daily and cumulative storage cleanup over time

Admin Panel - Keep Requests

<img src="assets/screenshots/request_queue.png" alt="Admin Queue" width="75%">

Admin interface for reviewing and approving user keep requests

Admin Panel - Keep or Sweep

<img src="assets/screenshots/keep_or_sweep.png" alt="Admin Keep or Sweep" width="75%">

Admin review interface for making final keep/delete decisions on media items

Scheduler Panel

<img src="assets/screenshots/scheduler.png" alt="Scheduler Panel" width="75%">

Control scheduler tasks and view cache statistics

---

🔧 Installation

Prerequisites

• Access to your Jellyfin ecosystem including:
  • Sonarr
  • Radarr
  • Jellystat or Streamystats
  • Jellyseerr

Docker Compose

For a quick deployment using Docker/Podman, create a compose.yml file:

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
      # - /data/movies:/data/movies:ro
      # - /data/tv:/data/tv: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
    # command:
    #   - serve
    #   - --log-level=debug

You can either supply the configuration via a `config.