Decluttarr: a queue janitor for the Arr suite that deletes what it can replace

A cleanup bot for the download queues, not a download client

Decluttarr is described as a helper tool that works with the Arr application suite and automates the clean-up of their download queues, keeping them free of stalled and redundant downloads. The applications it supports are Radarr, Sonarr, Sportarr, Readarr, Lidarr and Whisparr.

The scope matters. This is not a download client and it does not replace one. It sits alongside the Arr applications and a torrent client, and its only job is to look at what is in the queue and decide what should not be there any more.

The list of jobs is the specification. It prevents the download of bad files and removes torrents with less than 100 percent availability. It removes downloads that failed to download, and downloads that failed to import. It removes downloads stuck downloading metadata, downloads that are missing files, and downloads belonging to movies, series or albums that have been deleted since the download started, which it calls orphans. It removes downloads that are repeatedly found to be slow, downloads that are stalled, and downloads for items that have been marked as unmonitored. It removes completed downloads from the client that match certain criteria. And it can periodically search for better content where a cutoff has not been reached, and for missing content that has not yet been found.

The last two are different in kind from the rest. The removal jobs subtract from a queue, the search jobs add to it, and together they describe a policy of continuous replacement rather than one-off cleanup.

The key behaviours section adds the pieces that make the removal jobs safe to run unattended. Removing a download automatically triggers a search for a new one and removes the partial files downloaded so far. Certain jobs add the removed download automatically to the blocklists of the Arr applications, so the same release is not grabbed again. Downloads that should not be touched can be tagged with a protection tag in qBittorrent. And there is a test mode that shows what the tool would do without it actually doing it.

Private trackers are where the design earns its keep

The private tracker handling is the part of the design that a general purpose cleanup script cannot do, and it is the clearest reason to look at this project rather than writing your own.

The documentation says that torrents of private trackers and public trackers can be handled in different ways. They can be removed, they can be skipped entirely, or they can be tagged as obsolete so that other programs can remove them once the seed targets have been reached. Those are three settings, and the third one is the interesting one.

The distinction exists because a private tracker release is not a file you can simply delete. Your download ratio and your seeding time are the currency, and removing a torrent before the seeding requirement is met can get an account banned rather than merely lose a download. The obsolete tag is a hand-off: the tool marks the torrent and lets something else, presumably something that can read the tracker status, decide when the seeding obligation is discharged.

The protection tag works in the same direction. Tagging a download in qBittorrent protects it from removal, which is what you need for the release you deliberately kept.

The dependency section then spells out the cost of not using qBittorrent, and it is more than one line. If you do not use qBittorrent, the speeds provided by the Arr applications are used when detecting slow downloads, which is less accurate than what qBittorrent returns when queried directly. The protection tag feature does not work. The feature that distinguishes private from public trackers does not work. And removal of bad files and of content below 100 percent availability does not work.

That is a fair trade if you use another client, since qBittorrent is described as recommended but not required, but it means the private tracker story is only fully implemented on one client.

The configuration is a YAML file, and V2 changed it

There are two ways to run the tool, and the documentation is explicit about both. Either it runs as a local script, invoking main.py, with settings maintained in a config.yaml. Or it runs as a Docker image, where the settings can be configured through docker-compose alone, or the config.yaml is used instead.

The compose approach is documented in two variants, one with a config file and one specifying all settings in the compose file, and the documentation marks the config file variant as recommended.

The settings are grouped into three sections. The general settings cover the log level, the test run flag, the timer, the request timeout, SSL verification, the list of download clients to ignore, the private and public tracker handling, the obsolete tag and the protected tag. The job defaults cover the maximum number of strikes, the minimum number of days between searches and the maximum number of concurrent searches. Then each individual job has its own settings, one per job in the list above.

The structure is sensible for a tool like this, since the general section holds the few things you always set and the job section holds the thresholds per rule.

The upgrade note is the part to read before anything else. Decluttarr V2 was released on November 1, 2025 with breaking config file changes, and the documentation has a dedicated section for upgrading from V1 to V2. A tool that deletes files and triggers searches is not a good candidate for running against a config it does not understand, and a renamed or restructured key would silently change a threshold rather than fail loudly.

The repository layout supports the two run modes. There is a main.py at the top level, a src directory, a config directory, a docker directory, a tests directory, a pyproject.toml and a ruff.toml. The pyproject file holds the pylint configuration, with a long list of disabled checks and inline comments explaining each, such as broad exception catching being allowed because health checks and best effort paths need it. The pytest section sets quiet output with short tracebacks, the test paths pointing at the tests directory, and a log format of timestamp, level, name and message:

[tool.pytest.ini_options]
addopts = "-q --tb=short -s"
log_cli_level = "INFO"
log_cli_format = "%(asctime)s - %(levelname)s - %(name)s - %(message)s"
log_cli_date_format = "%Y-%m-%d %H:%M:%S"

The isort profile is set to black, so the import formatting matches the black style.

The test mode is the only safe way to try this

The single most important configuration flag for a new user is the test run, and the documentation describes it as letting you see what Decluttarr would do without it actually doing it.

That matters more here than for most tools, because the tool's output is deletion. It removes torrents, it removes the partial files of a failed download, it adds entries to blocklists, and it triggers new searches that will pull down more data. Getting the thresholds wrong does not produce an error message, it produces a queue that has been emptied of things you wanted and refilled with things the tool chose.

The job defaults are where the risk concentrates. The maximum number of strikes is the number of times a download has to be found in a bad state before the tool acts, and it is the difference between a download that was briefly slow and a download that is genuinely dead. The minimum number of days between searches and the maximum number of concurrent searches limit how hard the search jobs hit your indexers, which is both a politeness matter and a way to avoid triggering rate limits or getting your indexer account flagged.

A second practical detail is in the dependencies section, and it will save an afternoon. If you see strange errors such as found 10 / 3 times, the documentation suggests turning on the setting Reject Blocklisted Torrent Hashes While Grabbing. On nightly Radarr, Sonarr, Readarr, Lidarr and Whisparr, that option sits under settings, then indexers, then the advanced options of each indexer, and on Prowlarr it is under settings, then apps, then the advanced settings of the relevant app.

The project also documents a case where nothing is removed at all: if you use qBittorrent and none of your torrents get removed, and the verbose logs say that all torrents are protected, then the protection tag is doing exactly what it is designed to do.

Version support and the absence of releases

Two operational facts will shape how you deploy this.

The first is the version requirement for the Arr applications. The documentation says to use Sonarr v4 and Radarr v5, otherwise certain features may not work correctly. That is a floor on the applications, not on Decluttarr, and it means an older Arr setup needs upgrading before the cleanup is fully functional.

The second is the branch layout, and the documentation opens by warning about it. The default view on the repository is the dev branch, but you are most likely using latest, as the getting started instructions say. The documentation therefore links two separate readme files, one for the latest branch and one for the dev branch, and tells you to make sure you change the branch of the readme if that is your case.

That is an unusual amount of care to spend on a readme, and it tells you something about the release process. The project has no GitHub releases at all, so there is no tag and no changelog entry to point at. Instead, the branch itself is the version, and the readme has to be duplicated to match. A user reading the default branch will get documentation for a configuration format that may differ from the one their container is running.

The last push to the repository was on 2026-10-11 and it is not archived, so the work is ongoing, and the default branch for the project is dev while the main branch is master, which is another sign of a two branch development model where latest is cut from dev.

The licence is GPL-3.0, with a LICENSE file in the repository root and a MAINTAINERS.md alongside a CONTRIBUTING.md. GPL-3.0 is a copyleft licence, which matters here because this is a tool you are likely to run as a container alongside other Arr services rather than a library you link into your own code, and the practical question of how you distribute a modified image is one your own counsel should answer rather than this page.

Where Decluttarr is the wrong tool

Three situations rule it out.

The first is a queue you want to keep. The remove_done_seeding job exists to clear completed downloads from the client that match certain criteria, and that is exactly what a user who seeds deliberately wants switched off. A library that never has a download removed by accident because the user tagged it is safe to run in a mode that does nothing, but a user whose whole purpose is seeding is not the target audience.

The second is a private tracker setup without qBittorrent. As the dependency section spells out, the protection tag, the private and public tracker distinction and the bad file removal all stop working. If your trackers are private and your client is not qBittorrent, the tool is running with its most valuable feature silently disabled.

The third is a heterogeneous download client setup. The general settings include a list of download clients to ignore, and the project supports multiple qBittorrent instances as well as multiple Arr instances, but the model is one tool talking to several known client types. There is no indication of support for arbitrary client APIs, so a setup with a client outside the qBittorrent family gets less.

There is also a design constraint that follows from the whole approach. The timer setting means the work is done on a schedule, which means the tool is operating on a queue that has already changed by the time it acts. A download judged stalled at one poll may have been progressing all along, and the strike count is the only defence. That is a reasonable design for a background janitor, and it is the reason the test mode and the strike defaults exist, but it does mean the tool is best understood as a policy applied to a snapshot rather than as a supervisor watching a live queue.

Editorial conclusion

Decluttarr fits a self hosted Arr user whose queue accumulates stalled and superseded downloads, and who wants the removal policy expressed as configuration rather than as a series of manual checks. It is the wrong choice if you keep a qBittorrent setup only for private trackers, because the protection tag, the private and public tracker distinction and the bad file removal all need qBittorrent, and it is the wrong choice for anyone who wants a history of what was removed and why beyond the log file. Before running it against a live queue, run it once in test mode and read the log line by line, and check the version you are on against the V2 configuration format, because the release on November 1, 2025 changed the config file with breaking changes and the repository's default branch is dev while most users are on latest.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. ManiMatter/decluttarr on GitHub
4. README