Cleanuparr: a strike system for the Servarr download queue

The problem Cleanuparr was built to fix

The README is unusually direct about its origin: Cleanuparr was created primarily to address malicious files, such as *.lnk or *.zipx, that were getting stuck in Sonarr and Radarr and required manual intervention. It links four Reddit threads from r/sonarr as the posts that made the project happen, including one titled as a PSA that Sonarr downloaded a virus. That is the shape of the problem. A download client reports a completed torrent, the arr tries to import it, finds nothing it recognises, and the item sits in the queue. Nothing crashes. Nothing alerts. The queue just grows, and the only fix is a human opening the web UI and deleting rows.

The audience follows from that. Cleanuparr is for people running the Servarr stack at home or on a small server, with at least one arr (Sonarr, Radarr, Lidarr, Readarr, Whisparr v2 or v3, Sportarr, LazyLibrarian) and at least one supported client (qBittorrent, Transmission, Deluge, uTorrent, rTorrent). If you run a single arr with a single client and never look at the queue, you are the target user. If you do not run an arr at all, nothing here applies to you.

Strikes, categories and the malware blocker

The core mechanism is a strike system. Cleanuparr marks bad downloads with strikes, and once a download reaches a configured maximum number of strikes it is removed and blocked. The README lists the conditions that earn strikes: failing to be imported by the arrs, being stalled or sitting in metadata downloading state, a low download speed, a high estimated completion time, being blocked by qBittorrent, or being caught by Cleanuparr's own Malware Blocker. The blocker works on patterns found by the community, and the repository root carries files named blacklist and blacklist_permissive alongside whitelist and whitelist_with_subtitles, which is where that pattern data lives.

Two details matter more than the feature list. First, removal is paired with a block, so the same bad release does not come back on the next search. Second, Cleanuparr can automatically trigger a search for downloads it removed from the arrs, which closes the loop without you opening the arr. There is also an ignore mechanism: certain torrent hashes, categories, tags or trackers can be excluded from processing entirely. That is the escape hatch for private-tracker content you would rather police yourself.

Beyond the queue: orphaned files and cutoff unmet

Cleanuparr is not only a cleaner. It searches for missing items across Radarr and Sonarr libraries, searches for quality upgrades for items that have not met their quality profile's cutoff (the README calls this Cutoff Unmet), and searches for custom format score upgrades with automatic score tracking. It also handles seeding: downloads that have been seeding for a certain amount of time are cleaned up. Orphan handling goes further than the arrs do. Cleanuparr removes downloads that are orphaned, have no hardlinks, or are no longer referenced by the arrs, with cross-seed support. It can also scan configured directories for files not claimed by any active torrent, move them to a dedicated orphaned directory, and optionally auto-purge.

That last capability is the one to think hardest about. A directory scan that moves files is a different class of operation from removing a queue entry. The README documents the behaviour and the optional purge, but it does not describe an undo. If you enable auto-purge on a directory that also holds files you care about, the project offers no documented rollback path.

Installing Cleanuparr with Docker and opening the web UI

The README gives a single docker run command as the quick start. It publishes port 11011, mounts /config for persistent state, and sets PORT, PUID, PGID and TZ as environment variables. Replace the host path on the left of the volume mount with a real directory on your machine before running it.

docker run -d --name cleanuparr \
  --restart unless-stopped \
  -p 11011:11011 \
  -v /path/to/config:/config \
  -e PORT=11011 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  ghcr.io/cleanuparr/cleanuparr:latest

Once the container is up, the README says to open a browser at http://localhost:11011. That is the web interface where download clients and arr apps are configured. The README does not walk through the first configuration screen; it points to the configuration guide in the documentation site for that, and to a separate Prerequisites page that it explicitly says to read before the detailed installation guide. For Docker Compose, health checks and other installation methods, the README defers to the Complete Installation Guide rather than reproducing the files here.

A managed instance is also offered through ElfHosted, bundled with Sonarr and Radarr, with a 7-day trial, for people who would rather not self-host. Platforms listed in the README are Docker, Windows, macOS, Linux and Unraid, and the repository has an installers/ directory alongside the container image.

Where Cleanuparr is the wrong tool

The honest limitation is that Cleanuparr is a second service with credentials to everything. To do its job it needs access to your arrs and to your download clients. That is a real expansion of the blast radius in a stack that already holds API keys for every component, and the README does not discuss threat modelling or credential scoping. If you are not comfortable with that, the strike system is not worth it.

Second, the malware detection is pattern based, drawn from community-contributed lists. Patterns catch what someone has already seen and written down. A novel naming trick that does not match the lists will pass through, and the README makes no claim otherwise. Treat the Malware Blocker as a filter for known junk, not as a guarantee.

Third, the speed and completion-time thresholds are judgement calls you have to make. Set the low-speed threshold too high on a slow but legitimate connection and you will remove downloads that would have finished. The ignore lists for hashes, categories, tags and trackers exist precisely because a global rule will eventually be wrong for some content, and if you do not maintain them you will be re-adding releases by hand.

Cleanuparr compared with decluttarr

The README credits ManiMatter/decluttarr as an inspiration, and it is the most direct alternative. The difference is in what each is. decluttarr is a queue cleaner: it watches the arrs and removes stalled or failed items according to rules. Cleanuparr starts from the same idea and adds the parts that make it a service rather than a script: a web interface on port 11011, a strike system that accumulates rather than removing on first sight, a community pattern list for known malware, orphaned-file scanning with an optional purge, and searches for missing items, cutoff unmet and custom format score upgrades. If all you want is stalled-download removal, decluttarr is the smaller dependency. If you want malware patterns, orphan handling and the upgrade searches in one place, Cleanuparr is the broader tool. The README also credits ThijmenGThN/swaparr and PaeyMoopy/sonarr-radarr-queue-cleaner, which are narrower still.

One thing the README does not address is SABnzbd. The supported download clients it lists are all torrent clients, so a Usenet-only setup is out of scope as documented.

Licence, releases and the cost of keeping up

Cleanuparr is licensed under GPL-3.0. If you run it as a container alongside your arrs, the licence is not something you interact with day to day. It matters if you intend to modify the source and distribute the result, or to embed it in a product, because the GPL's copyleft terms attach to distributed derivative works. That is a general property of the licence, not legal advice, and anyone planning to redistribute should read the LICENSE file at the repository root.

The upgrade cost is visible in the release cadence. v2.10.8 landed on 2026-09-24, v2.10.7 on 2026-09-22, and v2.10.6 on 2026-09-14, with the last push to main on 2026-09-27. Three patch releases inside two weeks is a fast-moving project, and the practical consequence is that you should pin a tag rather than track latest if you want a stable queue cleaner. The README's own command uses the latest tag, which means every restart can pull a different build. The repository has a RELEASING.md and a CLAUDE.md at the top level, and a .github/ directory, so the release process is documented for contributors even though the README does not describe an upgrade procedure for operators.

Editorial conclusion

Adopt Cleanuparr if you run Sonarr or Radarr with qBittorrent, Transmission, Deluge, uTorrent or rTorrent and you are tired of clearing the same stalled or unimportable download by hand; the strike system and the malware blocker address a failure mode the arrs leave to you. Do not adopt it if your queue is already clean, if you want a search-and-upgrade tool rather than a queue cleaner, or if you are unwilling to hand a second service credentials for both your arrs and your download client. Before you commit, read the Prerequisites page the README links to, confirm your download client version is one of the supported ones, and check whether you need to set PORT, PUID, PGID and TZ for your host.

Frequently asked questions

Official sources

1. Cleanuparr/Cleanuparr on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases