Repolode
Submit
JudoChinX

JudoChinX/rangarr

Orchestration service that staggers and interleaves automated searches across Radarr, Sonarr, Lidarr, Readarr and Whisparr instances to protect indexers and API limits.

View on GitHub
Stars
265
Forks
7
Open issues
0
Last commit
28 days ago

What is it?

Rangarr is a lightweight service that coordinates automated media searches across several *arr instances: Radarr, Sonarr, Lidarr, Readarr and Whisparr (v2 and v3). Instead of letting each instance fire searches at the same time, it allocates a global pool of search slots, interleaves requests between instances and shared indexers, and spaces them out so that indexers and API limits are not overwhelmed.

Search behavior is configurable. Missing-item searches and upgrade searches run on separate intervals, weighted distribution can prioritize certain instances, and tag filters or active-hour windows limit which items are searched and when. Sonarr and Whisparr v2 searches can be grouped by season, and Radarr, Sonarr and Whisparr items below their custom format score target can be included, which *arr's Cutoff Unmet endpoint does not return.

Configuration lives in a config.yaml file with environment variable expansion, or can be done entirely through environment variables. The project runs as a Docker container, communicates only with the *arr instances you define, and stores no database or persistent state.

Key features

  • 01Manages Radarr, Sonarr, Lidarr, Readarr, Whisparr v2 and v3 from one service.
  • 02Distributes search slots globally and interleaves requests across instances.
  • 03Runs missing-item and upgrade searches on independent schedules.
  • 04Groups Sonarr and Whisparr v2 searches by season, with fallback to episodes for airing seasons.
  • 05Finds items below custom format score targets that Cutoff Unmet misses.
  • 06Filters searches by tags and limits them to configured active hours.

Use cases

  • Running a large Radarr and Sonarr library without flooding a shared indexer with searches.
  • Searching for missing content aggressively while checking for upgrades less often.
  • Limiting automated searches to overnight hours to avoid peak indexer load.
  • Deploying the service alongside existing *arr containers in Docker Compose.

Quick start

  1. 1

    Download the example config.yaml and compose.yaml from the repository, rename them, and set file permissions

  2. 2

    Edit config.yaml with your *arr API keys and hostnames

    nano config.yaml
  3. 3

    Start Rangarr with Docker Compose (keep dry_run: true until logs look correct)

    docker compose up -d

Things to know

  • You need existing Radarr, Sonarr, Lidarr, Readarr or Whisparr instances and their API keys.
  • Setup is configuration-heavy, requiring a hand-written config.yaml or many environment variables.

In collections

Self-hosted apps

Topics

#media-automation#radarr#sonarr#lidarr#docker#self-hosted#indexer#python

FAQ

What is rangarr?
Orchestration service that staggers and interleaves automated searches across Radarr, Sonarr, Lidarr, Readarr and Whisparr instances to protect indexers and API limits. Rangarr is a lightweight service that coordinates automated media searches across several *arr instances: Radarr, Sonarr, Lidarr, Readarr and Whisparr (v2 and v3). Instead of letting each instance fire searches at the same time, it allocates a global pool of search slots, interleaves requests between instances and shared indexers, and spaces them out so that indexers and API limits are not overwhelmed.
Is rangarr free to use? What license does it have?
rangarr is open source under the MIT license. Check the license terms before using it in commercial products.
Is rangarr still maintained?
Actively maintained. The last commit to rangarr was on Oct 10, 2026.
What can I use rangarr for?
Running a large Radarr and Sonarr library without flooding a shared indexer with searches. Searching for missing content aggressively while checking for upgrades less often. Limiting automated searches to overnight hours to avoid peak indexer load. Deploying the service alongside existing *arr containers in Docker Compose.
How do I install rangarr?
Download the example config.yaml and compose.yaml from the repository, rename them, and set file permissions Edit config.yaml with your *arr API keys and hostnames: nano config.yaml Start Rangarr with Docker Compose (keep dry_run: true until logs look correct): docker compose up -d
Where can I get rangarr?
The source code and installation instructions are on GitHub: https://github.com/JudoChinX/rangarr

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects