How to Implement Custom IP Blocklists in qBittorrent: Complete Technical Guide

qBittorrent implements custom IP blocklists through three integrated layers—user configuration management in SessionImpl, asynchronous file parsing via FilterParserThread, and direct libtorrent session filtering—supporting DAT (eMule), P2P (PeerGuardian), and P2B (binary) formats.

Implementing custom IP blocklists in qBittorrent prevents unwanted peer connections by filtering IP ranges before they reach the BitTorrent protocol layer. According to the qbittorrent/qBittorrent source code, this feature spans src/base/bittorrent/sessionimpl.cpp, background parsing threads, and direct integration with the underlying libtorrent session to apply rules at the network level.

Architecture of IP Filtering

The IP filtering system operates across three tightly-coupled layers that bridge user preferences to low-level network blocking.

Configuration Layer (SessionImpl)

The session management layer in src/base/bittorrent/sessionimpl.h stores the filtering state through two cached settings: CachedSettingValue<bool> m_isIPFilteringEnabled and CachedSettingValue<Path> m_IPFilterFile. These correspond to the "Enable IP Filtering" toggle and the blocklist file path.

When settings change, SessionImpl::configureComponents() evaluates isIPFilteringEnabled(). If true, it invokes enableIPFilter(); otherwise, it calls disableIPFilter(). The enable method constructs a FilterParserThread instance, sets m_filePath to your specified blocklist location, and initiates background parsing in src/base/bittorrent/filterparserthread.cpp.

Parsing Layer (FilterParserThread)

File parsing occurs asynchronously to prevent UI blocking. The FilterParserThread::run() method detects your file extension and delegates to one of three specialized parsers:

• DAT parser (parseDATFilterFile()) for eMule format
• P2P parser (parseP2PFilterFile()) for PeerGuardian text format
• P2B parser (parseP2BFilterFile()) for PeerGuardian binary format

Each parser extracts start and end IP addresses, validates them using parseIPAddress(), and inserts rules into a local lt::ip_filter instance via m_filter.add_rule(startAddr, endAddr, lt::ip_filter::blocked). Upon completion, the thread emits IPFilterParsed(ruleCount), which SessionImpl captures to update the active filter.

Application Layer (Libtorrent)

The filter synchronization happens in SessionImpl::handleIPFilterParsed(int ruleCount) inside src/base/bittorrent/sessionimpl.cpp. This method applies the constructed filter to the native session:

m_nativeSession->set_ip_filter(m_filterParser->IPfilter());

This call updates libtorrent's built-in IP filter, causing immediate rejection of any inbound or outbound connection attempts matching blocked ranges.

Supported Blocklist Formats

qBittorrent recognizes three industry-standard formats based on file extension detection in FilterParserThread::processFilterFile():

• DAT – eMule IP filter format (plain text)
• P2P – PeerGuardian text format (IP ranges with descriptions)
• P2B – PeerGuardian binary format (compiled binary)

Enabling Custom Blocklists

Via the GUI

The graphical interface definition resides in src/gui/optionsdialog.ui, exposing controls through the checkIPFilter checkbox and textFilterPath line edit. To activate a blocklist:

1. Navigate to Options → Connection → IP Filtering
2. Enable "IP Filtering" (toggles checkIPFilter)
3. Click the folder button next to "Filter file" to populate textFilterPath
4. Click OK to trigger OptionsDialog::apply(), which writes to Preferences::setIPFilteringEnabled() and Preferences::setIPFilterFile()

Via the Web API

For headless instances, the Web API controller in src/webui/api/appcontroller.cpp exposes the same functionality:

curl -X POST http://localhost:8080/api/v2/app/setPreferences \
  -d 'json={"ip_filter_enabled":true,"ip_filter_path":"/home/user/custom_blocklist.dat"}'

The AppController::setPreferences() method reads ip_filter_enabled and ip_filter_path, then calls session->setIPFilteringEnabled() and session->setIPFilterFile() to trigger the parsing pipeline.

Programmatically (C++)

To enable filtering from within the codebase or plugins:

#include "base/bittorrent/session.h"
#include "base/utils/fs.h"

using namespace BitTorrent;

Session *session = Session::instance();
session->setIPFilteringEnabled(true);
session->setIPFilterFile(Path::fromString(u"/path/to/my_blocklist.p2p"));
session->configureDeferred();  // Triggers immediate reconfiguration

This updates the internal m_isIPFilteringEnabled and m_IPFilterFile members before scheduling configureDeferred() to apply changes.

Reloading Blocklists Without Restart

To reload a modified blocklist file without restarting the application, toggle the IP Filtering setting off then on again. This sequence forces disableIPFilter() followed by enableIPFilter() in sessionimpl.cpp, which creates a fresh FilterParserThread and re-parses the file from disk. Alternatively, updating the file path and calling session->configureDeferred() triggers the same reload mechanism.

Summary

• qBittorrent implements IP blocklists through SessionImpl configuration, FilterParserThread parsing, and libtorrent set_ip_filter() application
• Three formats are supported: DAT, P2P, and P2B, parsed in src/base/bittorrent/filterparserthread.cpp
• GUI controls reside in src/gui/optionsdialog.ui with checkIPFilter and textFilterPath widgets
• Web API exposes ip_filter_enabled and ip_filter_path parameters via AppController
• Reload blocklists by toggling the filter off/on or invoking configureDeferred() to spawn a new parser thread

Frequently Asked Questions

What file formats does qBittorrent support for IP blocklists?

qBittorrent supports three formats as implemented in FilterParserThread::processFilterFile(): DAT (eMule format), P2P (PeerGuardian text format), and P2B (PeerGuardian binary format). The parser detects the format by file extension and uses parseDATFilterFile(), parseP2PFilterFile(), or parseP2BFilterFile() respectively to populate the lt::ip_filter object.

How do I reload a blocklist without restarting qBittorrent?

Toggle IP Filtering off then on in the GUI, or programmatically call session->setIPFilteringEnabled(false) followed by session->setIPFilteringEnabled(true). This triggers disableIPFilter() and enableIPFilter() in sessionimpl.cpp, spawning a new FilterParserThread to reload and parse the file from disk.

Where does qBittorrent store IP filtering settings?

Settings persist through the Preferences class and are cached in SessionImpl as m_isIPFilteringEnabled (boolean) and m_IPFilterFile (path). These values are declared in src/base/bittorrent/sessionimpl.h and written via Preferences::setIPFilteringEnabled() and Preferences::setIPFilterFile().

Can I use multiple blocklist files simultaneously?

The current implementation in sessionimpl.cpp supports only a single active blocklist file path via m_IPFilterFile. To combine multiple lists, concatenate them into a single DAT, P2P, or P2B file before loading, or alternate between files by updating the path and triggering a reload through the Web API or GUI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}