arr/blocklists
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Consumers
Pages
CI and Workflow Consumers Lists Sync
Clone
2
Consumers
CodeX edited this page 2026-04-07 02:12:52 +02:00
Table of Contents

Consumers

The blocklists are consumed by Cleanuparr. qBittorrent itself does not read any URL from this repository -- the only direct consumer is Cleanuparr, which exposes two independent features that each pull a different file:

Cleanuparr feature File consumed What it does
Blocklist Sync blacklist Pushes the full pattern set to qBittorrent's "Excluded file names" via the qBittorrent Web API
Malware Blocker whitelist (whitelist mode) or blacklist (blacklist mode) Inspects torrents in the Sonarr/Radarr queue and removes ones that violate the rules

The two features are configured independently in Cleanuparr's settings, each with its own URL and refresh schedule. Use both, either, or neither. This repository is set up so that both can be used together: Blocklist Sync against blacklist, Malware Blocker against whitelist in whitelist mode.

Raw URLs

Point Cleanuparr's features at the raw file URLs, not the Gitea blob viewer URLs:

https://git.hisp.no/arr/blocklists/raw/branch/main/blacklist
https://git.hisp.no/arr/blocklists/raw/branch/main/whitelist

The raw/branch/main/ path serves the file contents directly with the correct text/plain content type. Using src/branch/main/ instead serves the HTML viewer page and will break the consumer.

Blocklist Sync (push to qBittorrent)

Cleanuparr's Blocklist Sync fetches a blocklist URL on its configured interval, then pushes the full pattern list into qBittorrent's "Excluded file names" setting via the qBittorrent Web API. The user does not configure qBittorrent's exclusion list directly -- everything happens through Cleanuparr.

What it supports

  • Blacklists only. There is no whitelist mode for Blocklist Sync.
  • Full replacement of qBittorrent's exclusion list on every push. Any patterns set manually in qBittorrent will be overwritten.
  • All connected qBittorrent instances receive the same list (one push per configured download client in Cleanuparr).

Configuration

In Cleanuparr's settings, enable Blocklist Sync and point it at:

https://git.hisp.no/arr/blocklists/raw/branch/main/blacklist

Cleanuparr fetches on its configured interval, then writes the patterns to qBittorrent. Check Cleanuparr's logs to confirm the push succeeded after each sync.

How qBittorrent uses the pushed list

Once Cleanuparr has pushed the patterns, qBittorrent treats them exactly the same as if they had been set manually. When a torrent is added, qBittorrent iterates the files inside it and checks each filename against the excluded patterns. Matching files are marked as "do not download" and will not be written to disk. The rest of the torrent downloads normally.

This means the list operates at the file level within a torrent, not the torrent level. A torrent containing movie.mkv and movie.nor.srt downloads both files because *.srt is in the whitelist (and therefore not in the pushed pattern list).

Why this URL

The blacklist file in this repository is the upstream Cleanuparr blacklist with the locally-maintained whitelist already subtracted. Anything in whitelist is therefore not pushed to qBittorrent, so subtitles, AV1 webm releases, and other extensions you want kept will not be excluded when qBittorrent downloads a torrent.

Malware Blocker (Sonarr/Radarr queue)

Cleanuparr's Malware Blocker inspects torrents in the Sonarr and Radarr download queues, examines the files they contain, and removes any torrent that violates the configured rules. It runs independently from Blocklist Sync and uses its own URL and refresh schedule.

What it supports

  • Whitelist mode -- only torrents whose contained files all match the whitelist patterns are kept. Everything else is removed from the queue.
  • Blacklist mode -- torrents containing any file matching the blacklist patterns are removed.
  • Sonarr and Radarr queues -- both supported, configured per-arr in Cleanuparr's settings.

Recommended mode and URL

This repository is configured for whitelist mode: a small explicit list of allowed extensions is easier to reason about than the much larger upstream blacklist, especially when the goal is "only let through legitimate video and subtitle files."

Point Malware Blocker at:

https://git.hisp.no/arr/blocklists/raw/branch/main/whitelist

In whitelist mode, only torrents whose contained files all have whitelisted extensions are allowed to remain in the queue. A torrent with movie.mkv and movie.nor.srt passes (both extensions are whitelisted). A torrent with movie.mkv and setup.exe is removed from the queue before it reaches qBittorrent.

If you would rather use blacklist mode, point Malware Blocker at the blacklist URL instead -- the same one Blocklist Sync uses. Both modes use the same data files; only the matching logic differs.

Why two layers are useful

Blocklist Sync and Malware Blocker operate at different layers:

  • Malware Blocker (queue layer) stops bad torrents from being added to qBittorrent in the first place. A torrent that fails the whitelist check never reaches the download client.
  • Blocklist Sync (file layer) keeps qBittorrent from writing individual junk files (samples, NFOs, mixed-in executables) to disk while still allowing the legitimate files in a release through.

Used together, the two layers give you a queue-level allow list and a file-level deny list, both maintained from the same whitelist source of truth.

Troubleshooting

A file I whitelisted is still being blocked

Check each layer in order:

  1. Sync ran successfully? Open the Gitea Actions page for the repository and verify the most recent run is green and newer than your whitelist commit.
  2. Blacklist was updated? Read blacklist in Gitea and confirm your whitelisted entry is no longer present.
  3. Cleanuparr refreshed? Blocklist Sync runs on its configured interval, not on demand. Check Cleanuparr's logs to confirm it picked up the new file. Trigger a manual run from Cleanuparr's UI if available.
  4. Cleanuparr pushed to qBittorrent? After fetching the new file, Cleanuparr writes it to qBittorrent. Check qBittorrent's Options -> Downloads -> Excluded file names and confirm the new list is in place.
  5. Exact string match? Whitelist entries must match blacklist entries exactly. *.srt in whitelist does not strip *sample.srt from blacklist. See Lists for pattern semantics.

A file I did not whitelist is passing through

Check whether the pattern is in the blacklist at all:

  1. Open blacklist in Gitea and search for the extension.
  2. If it is not there, upstream Cleanuparr does not block it. You can add it to blacklist directly (manual local addition, preserved by the three-way merge) or file an upstream issue.

Cleanuparr returns 404 for the blocklist URL

Verify the URL uses raw/branch/main/, not src/branch/main/:

# Correct
https://git.hisp.no/arr/blocklists/raw/branch/main/blacklist

# Wrong (serves HTML, not the file)
https://git.hisp.no/arr/blocklists/src/branch/main/blacklist

Also check the repository name and branch are correct (arr/blocklists, main).

Malware Blocker is removing legitimate torrents

Make sure Malware Blocker is in whitelist mode and pointed at whitelist, not blacklist. In blacklist mode it uses the much larger upstream blacklist and may remove a torrent that contains a single junk file inside an otherwise legitimate release.

Blocklist Sync did not push to qBittorrent

Check Cleanuparr's connection to qBittorrent:

  1. Cleanuparr settings -> Download clients -- verify the qBittorrent host, port, username, and password.
  2. Cleanuparr logs -- look for Blocklist Sync errors after the most recent scheduled run. Connection failures are logged at error level.
  3. qBittorrent Web API enabled -- the push uses the Web API, which must be enabled in qBittorrent's options under Web UI.