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.

qbt-clean --config=config.scfg simulate

clean

Clean torrents until space target is reached.

qbt-clean --config=config.scfg clean

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.

qbt-clean --config=config.scfg groups

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

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 last override for every requirement will apply.

Additionally, 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 the categories-allowed requirement anymore. So be very careful that all rules that apply pin: false are very particular about what you want to never pin.

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.

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.

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.