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

> Master custom IP blocklists in qBittorrent with our complete technical guide. Learn to implement DAT, P2P, and P2B formats for enhanced security and privacy.

- Repository: [qBittorrent project/qBittorrent](https://github.com/qbittorrent/qBittorrent)
- Tags: how-to-guide
- Published: 2026-05-05

---

**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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/sessionimpl.cpp). This method applies the constructed filter to the native session:

```cpp
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`](https://github.com/qbittorrent/qBittorrent/blob/main/src/webui/api/appcontroller.cpp) exposes the same functionality:

```bash
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:

```cpp
#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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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.