Conductarr

🎼 Priority-based download queue orchestrator for Radarr, Sonarr & SABnzbd — automatically manages and reorders your download queue across multiple priority tiers.

What it does

Conductarr sits between Radarr/Sonarr and SABnzbd and does two things:

• Queue ordering — every SABnzbd job is mapped to a virtual queue (e.g. user requests, other, upgrades) via tag matchers. The SABnzbd queue is kept in priority order, and by default only the top job downloads while the rest are paused. Conductarr-initiated upgrades always sort below everything else.
• Gradual library upgrades — for queues with an upgrade section, conductarr walks your whole library, finds movies/episodes whose file does not yet satisfy your accept_conditions (e.g. the German DL custom format), runs an interactive search through the Arr, and grabs the best release that is a real improvement — one item at a time, rate-limited, and only when nothing else is downloading.

Radarr/Sonarr themselves never need to upgrade anything; conductarr decides what to grab, the Arr does the actual import.

Safety model

Conductarr is built so that it cannot damage your library or disturb normal downloads:

Quick start (Docker Compose)

services:
  conductarr:
    image: ghcr.io/eulemitkeule/conductarr:latest
    container_name: conductarr
    restart: unless-stopped
    environment:
      PUID: 1000
      PGID: 1000
      UMASK: "022"
      TZ: Europe/Berlin
      LOG_LEVEL: info
    volumes:
      - /path/to/conductarr/config:/config
    command: conductarr watch

Conductarr only needs its own config directory — it never needs access to your media or download folders.

Place a conductarr.yml inside the config directory; config.example.yml documents every option. Unknown keys are rejected at startup, so typos cannot silently disable a safety setting.

Recommended rollout

1. Start with dry_run: true and watch the log for a day: every "would grab", "would pause" and "would move" line shows exactly what conductarr would do.
2. Try a single item: conductarr debug-upgrades --source radarr --id 42 (performs one real indexer search, grabs nothing).
3. Switch to dry_run: false with max_active: 1.

Commands

How it works

Two independent loops run every poll_interval:

Queue loop

1. Read the SABnzbd queue.
2. Map new nzo_ids to Radarr/Sonarr items via their queues (one fetch per cycle). Jobs that could not be mapped are retried every minute.
3. Finalise jobs that left the queue once SABnzbd history reports Completed/Failed (post-processing is waited for). Jobs deleted without history are released after 30 minutes.
4. Reorder by virtual-queue rank and keep one job active.

Upgrade loop (per upgrade queue)

1. Rescan the libraries every rescan_interval: every movie/episode with a file becomes a candidate, including items that were first downloaded as a user request.
2. Skip if max_active grabs are in flight, SABnzbd is paused/low on space, other downloads are waiting, or the search budget is used.
3. Walk candidates from a persisted cursor; items that already satisfy the conditions, have no file or are downloading are skipped without searching.
4. Search the first real candidate, run the selection pipeline (usenet → conditions → mapping → rejections → downloadable → blocklist → resolution → score) and grab the best remaining release.

The grab is recorded in the database before the Arr is asked to grab it, so a download can never go untracked.

Development

uv sync --all-groups
uv run pytest tests/unit                 # fast, no services needed
uv run pytest tests/integration          # starts mock SABnzbd/Radarr/Sonarr via docker compose
uv run ruff check . && uv run ty check