https://github.com/jessielw/Reclaimerr
Automatically reclaim space in your media library using customizable rules. Integrates with Jellyfin, Plex, and Emby (any or all of them) to analyze and manage your content. Functions similarly to Seerr (in reverse), providing efficient media cleanup and organization
https://github.com/jessielw/Reclaimerr
clean cleanse delete docker emby emby-server jellyfin maintance movies plex radarr reclaim reclaimerr restore series sonarr sweep tv
Last synced: 21 days ago
JSON representation
Automatically reclaim space in your media library using customizable rules. Integrates with Jellyfin, Plex, and Emby (any or all of them) to analyze and manage your content. Functions similarly to Seerr (in reverse), providing efficient media cleanup and organization
- Host: GitHub
- URL: https://github.com/jessielw/Reclaimerr
- Owner: jessielw
- License: gpl-3.0
- Created: 2026-01-03T03:43:43.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-30T18:59:41.000Z (24 days ago)
- Last Synced: 2026-04-30T19:17:16.093Z (24 days ago)
- Topics: clean, cleanse, delete, docker, emby, emby-server, jellyfin, maintance, movies, plex, radarr, reclaim, reclaimerr, restore, series, sonarr, sweep, tv
- Language: Python
- Homepage:
- Size: 7.31 MB
- Stars: 439
- Watchers: 4
- Forks: 7
- Open Issues: 42
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
**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](https://github.com/Maintainerr/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](https://github.com/Maintainerr/Maintainerr/releases/tag/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](https://github.com/jessielw/Reclaimerr/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](https://appriseit.com/services/), 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](https://github.com/jessielw/Reclaimerr/releases) 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**
```yaml
# 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**
```yaml
# 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**
```yaml
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](https://docs.astral.sh/uv/)
1. Clone the repository
```bash
git clone https://github.com/jessielw/Reclaimerr.git
cd Reclaimerr
```
2. Install Python dependencies
```bash
uv sync
```
3. Create your environment file and fill in the required values (see the Docker `.env` example above)
```bash
cp .env.example .env
```
4. Start the backend
```bash
uv run uvicorn backend.api.main:app
```
5. Start the frontend
```bash
cd frontend
npm install
npm run dev
```
The backend is available at [http://localhost:8000](http://localhost:8000) and the frontend at [http://localhost:3000](http://localhost:3000).
## Preview
## Contributing
[Contribution guide](docs/CONTRIBUTING.md)
## Credits
- [Maintainerr](https://github.com/Maintainerr/Maintainerr) and [Seerr](https://github.com/seerr-team/seerr) for inspiration
- [TheMovieDB](https://www.themoviedb.org/)
- Numerous community dependencies (see [pyproject](pyproject.toml) and [package](frontend/package.json))