qbt-clean
A tool for cleaning up torrents in qBittorrent. The defining feature is that it attempts to identify groups of torrents that are the same content. For example torrents that are likely hard-linked or ref-linked to the same underlying data.
[!warning] This is a tool to data data, it will do so. It is highly recommended to run in dry-run (the default) first and validate that it is deleting what you expect.
Additionally this tool is very new and not particularly well tested. Additionally the configuration is constantly changing at these early stages.
USE AT YOUR OWN RISK
Commands
simulate
Simulate is equivalent to clean except that it doesn't actually modify anything. Use it to see what would be cleaned.
clean
Clean torrents until space target is reached.
groups
Show grows as well as info about them such as if they are pinned or not and what rank they are in the cleaning order. Use --help for more options.
Grouping
The current grouping is incredibly simple. It just sums up the size of substantial files in each torrent. Any files that share the exact same total size are considered a group.
Config
Operational Config
target-free
Clean up torrents until this much space is free on the filesystem.
Note: This assumes that each deleted group frees up the amount of the space of the torrent size. This can underestimate (if the backing blocks are still used by other files) or overestimate (if the torrents in the group did not share data).
target-free: 100 GiB
qbt-url
The URL to interact with qBittorrent at. This should also contain the username and password for authentication.
qbt-url: http://localhost:8080
parallelism
The parallelism to use. This roughly corresponds to the number of concurrent requests to qBittorrent.
The default is currently 16 which strikes a balance between performing reasonably in high-latency environments and not unnecessarily loading qBittorrent. Local users can probably use a much lower number, especially if total execution time isn't very important.
Requirements
These requirements prevent cleaning up torrents that shouldn't be. They are applied to each torrent in a group individually. Any torrent in a group that fails to satisfy a requirement will prevent the entire group from being removed.
The default values are been show.
categories-allowed
The torrent must be in one of these categories to be cleaned up.
There are no defaults (meaning that if this isn't set no torrents will match).
last-activity-min
If the torrent was active within this period it won't be cleaned up.
last-activity-min: 7d
names-pinned
If the torrent name matches any of these regexes it won't be cleaned up. These must match the full name.
There are no defaults.
trackers-pinned
If any of the tracker URLs name match any of these regexes it won't be cleaned up. These must match the full tracker URL.
There are no defaults.
seed-time-min
If the total torrent seed time is less than this it won't be cleaned up.
seed-time-min: 14d
seeder-count-min
If the torrent doesn't have this many seeders it won't be cleaned up.
seeder-count-min: 3
state-allowed
If the torrent isn't in one of these states it won't be cleaned up. These can be specified with either the identifiers that qBittorrent uses or more consistent kebab-case versions.
state-allowed:
error
missing-files
stopped
stopped-downloading
stopped-uploading
uploading-forced
uploading-queued
uploading-stalled
If this field is empty, then any state is allowed.
Rules
Rules allow you to override the requirements for specific torrents. For example the following rule will avoid cleaning up Archive.org torrents unless they have at least a year of seed time. Note that this applies only to the specific torrent. Other torrents in the group may have less seed time when cleaned up.
rules:
:
match:
tracker-url:
http://bt\d+.archive.org:6969/announce
seed-time-min: 365d
Rules consist of a match: block which contains filters and then a set of requirements to override when the filters match. Only the first override for every requirement will apply.
Effects
Global Requirements
All global requirements can be modified with an attribute of the same name.
pin
There is a special pin requirement that overrides any other requirement. So a filter that applies pin: true will prevent a torrent (and it's group) from ever being deleted. pin: false will prevent a torrent from ever holding a group alive (but other torrents in the group may keep it alive). Just like other requirements only the last pin rule that matches applies.
[!warning] Be very careful with
pin: false. It overrides all requirements and is very easy to delete more than you intended. For example do you have an "Important Never Delete" category? It won't be protected by thecategories-allowedrequirement anymore. So be very careful that all rules that applypin: falseare very particular about what you want to never pin.
include-in-score
This value is a boolean that allows excluding torrents from the group score. This is commonly used with pin: false. Additionally configuring the no-scored-torrents-weight to influence the score of groups containing only include-in-score: false torrents.
Matchers
any
The any filter takes a list of filters and matches if any of them match.
This example will set the minimum seeder count if either a specific tracker is on the torrent or it is in the favourites category.
rules:
:
match:
any:
:
tracker-url:
https://tracker.example
:
categories:
favourites
seeder-count-min: 10
categories
The categories filter matches torrents that are in the given categories.
rules:
match:
categories:
Favourites
Keep Forever
Note: There is also a categories-allowed requirement.
is-private
Match based on if the torrent is marked as private or not.
rules:
:
match:
is-private: true
last-activity
Match based on when the torrent was last active.
rules:
:
match:
last-activity:
lt: 1d
leech-count
Match the number of leechers.
rules:
match:
leech-count:
gt: 10
name
Match any torrents who's name matches the regex.
rules:
:
match:
name:
Arch.*\.iso
none
Match if none of the given filters match:
rules:
match:
none:
:
seed-count:
lt: 10
leech-count:
lt: 10
seed-time
Match based on the seed time for the torrent.
rules:
:
match:
seed-time:
gt: 1h
ratio
Match based on the ratio of the torrent.
rules:
match:
ratio:
ge: 8
seed-count
Match the number of seeders.
rules:
match:
seed-count:
ge: 10
state
Match if the torrent state is in any of the listed states.
rules:
:
match:
state:
stopped-downloading
uploading-forced
tracker-msg
Match if any of the tracker's tracker messages matches any of the given regexes.
rules:
:
match:
tracker-msg:
[Uu]nregistered torrent
Torrent has been deleted.
tracker-msg
Match if any of the tracker URLs match any of the given regexes.
rules:
:
match:
tracker-url:
http://bt\d+.archive.org:6969/announce
Ranking
Ranking determines which torrents to delete first. The highest ranked torrents will be deleted until the desired space is reclaimed.
All ranking parameters take a floating point number and default to zero. If all ranking parameters are zero seeder-count-weight: 1.0 will be applied.
age-d-max-weight
Rank based on the age of the oldest torrent in the group.
Note: If you want to prefer keeping older torrents the weight should be negative.
age-d-min-weight
Rank based on the age of the newest torrent in the group.
Note: If you want to prefer keeping older torrents the weight should be negative.
copies-weight
Rank based on number of torrents in the group.
Note: If you want to prefer keeping larger groups the weight should be negative.
last-activity-d-weight
Rank based on the last activity in the group.
no-scored-torrents-weight
If a group has no scored torrents, apply this weight. (See include-in-score)
seeder-count-weight
Rank based on total seeder count.
size-weight
Rank based on the size expected to be freed by deleting.
Note: This is roughly the size of a torrent in the group.