Reclaimerr is designed to help you reclaim disk space from your media library. I was inspired to create Reclaimerr when the 100TB of storage on my home server was nearly full and I saw the rising cost of new drives. I realized it was time to start cleaning up all the unwatched and low-rated media on my server.

I explored numerous open source applications for server cleanup, and Maintainerr stood out as a major inspiration for Reclaimerr's design. When I began development, Maintainerr didn't support Jellyfin or Emby, though support was added to Jellyfin in v3.0.0, it still didn't fully meet my needs.

I needed a solution to manage a single physical media library while utilizing both Jellyfin and Plex to run filters and rules. I considered contributing to Maintainerr, but its codebase was undergoing a major refactor to add Jellyfin support. Same as with Maintainerr - Reclaimerr can also be run without Sonarr/Radarr, directly integrated with Jellyfin/Plex.

Driven by the increasing cost of storage and the need to reclaim used disk space, inspired by Maintainerr, Reclaimerr was born.

Star History

Discussions

While I prefer we utilize github's discussions for historical purposes, I've had quite a few users ask for Discord. I personally am getting away from Discord ASAP, but I did create a public matrix server for discussions and some support. Feel free to join https://matrix.to/#/#reclaimerr:matrix.org!

AI Disclosures

AI (LLMs) are everywhere and everyone is using them. I understand that many users are concerned about projects heavily generated by AI or lacking a personal touch. Reclaimerr was built from the ground up and was not generated using LLMs or a fork of any other project.

LLMs have only been used as a tool for tasks such as searching for information, automating repetitive work, debugging, occasional CSS/UI assistance, and minor grammar suggestions/fixes. All design and code have been written by hand, ensuring I have a deep understanding on how all the gears turn. Even this readme here is hand written and then I utilized an LLM to correct grammar and clarity 😆.

As a result, this project will close pull requests that appear to be mostly or wholly AI generated.

Features

• Configure rules to automatically reclaim disk space
• Supports Jellyfin, Plex, and Emby (all at once if needed)
  • Designate one server as the main server; supplemental data (such as watch history) is gathered from the others if using more than one media server. Note: All servers must manage the same physical media library
• Configurable task scheduling (cron/time based)
• Automatically scans media eligible for reclamation
• Media library items protection system
  • This system adds "protection" that will prevent them from being considered for deletion
  • Users can request protection (to be approved or denied by users with appropriate permissions)
  • Time based control for protection duration
• Multi-user support with a permission system
• Notifications via Apprise, supporting over 133 services at the time of writing
• Remove or unmonitor media from Radarr and Sonarr (if configured)
• Remove requests from Seerr
• Delete files from disk
  • If Radarr or Sonarr are configured, Reclaimerr processes deletion through them, only falling back to the main server if needed
• Very lightweight and efficient; avoids spinning up disks outside of deletions (all data is sourced directly from your media servers)
• Light and dark mode
• Responsive UI (works great on mobile)

Additional Info

• While Reclaimerr is in early beta, the task to automatically delete media will not be enabled or visible in the UI. I do not want to risk permanent deletion of anyone's media due to a bug with full automation until the things have been thoroughly tested.
  • For now, only admins or users with appropriate permissions can manage deletions through the UI or API
  • Once automatic deletions are added it will be opt in
• While Reclaimerr is in beta, things are subject to change in response to user feedback and testing
• Proper documentation will be made as the app matures a bit more

Install

Desktop

You can use the latest release for your platform if there is a build available.

Note: Desktop builds for Windows must be ran from Windows 8 or greater

How to use

You can simply execute the prebuilt binary and it'll create a tray icon.

• Double click (or right click the tray icon and choose "Open") to automatically open a window in your browser.
  • The server defaults to port 8000 (as of v0.1.0-beta8). If the default port (or your chosen port) is taken, the server will attempt to find an open port within the next 10 ports.
• Right click and choose "Close" to cleanly stop the application.

Configuration

As of v0.1.0-beta8, you can control a few customizable options via a .env file. Simply place this file beside your executable before launching the server, and it will prioritize these settings.

Example Desktop .env

# All of these are optional. For example, to change the port to 8049:
API_PORT=8049
# API_HOST=127.0.0.1
# CORS_ORIGINS=http://localhost:3000
# optional (only use if you want to reset or set the admin password on first launch, min 3 / max 64)
# ADMIN_PASSWORD=

Docker

Example .env

# directory to store application data (database, logs, static files, etc.)
DATA_DIR=./data

# API configuration
API_HOST=0.0.0.0
API_PORT=8000
CORS_ORIGINS=http://localhost:3000

# secrets — leave blank to auto-generate stable values on first launch (recommended),
# or set your own (min 32 characters, e.g. `openssl rand -hex 32`)
# JWT_SECRET=
# ENCRYPTION_KEY=

# logging (options: DEBUG, INFO, WARNING, ERROR, CRITICAL)
# LOG_LEVEL=INFO

# optional (only use if you want to reset or set the admin password on first launch, min 3 / max 64)
# ADMIN_PASSWORD=

# set to true when serving over HTTPS
# COOKIE_SECURE=false

Example compose

services:
  reclaimerr:
    image: ghcr.io/jessielw/reclaimerr:latest
    container_name: reclaimerr
    restart: unless-stopped
    env_file: ".env"
    volumes:
      - ./data:/app/data
    ports:
      - "8000:8000"

Reset Admin Password

To reset the admin password, set the ADMIN_PASSWORD environment variable and restart the application. The new password will be applied to the admin account on startup.

Note: For security, it is recommended to remove or unset this variable after the application has started and the password has been updated.

Run from Source

Requirements: Python 3.11+, Node.js 20+, uv

1. Clone the repository

git clone https://github.com/jessielw/Reclaimerr.git
cd Reclaimerr

2. Install Python dependencies

uv sync

3. Create your environment file and fill in the required values (see the Docker .env example above)

cp .env.example .env

4. Start the backend

uv run uvicorn backend.api.main:app

5. Start the frontend

cd frontend
npm install
npm run dev

The backend is available at http://localhost:8000 and the frontend at http://localhost:3000.

Preview

Contributing

Contribution guide

Credits

• Maintainerr and Seerr for inspiration
• TheMovieDB
• Numerous community dependencies (see pyproject and package)