# Configuring SOCKS5 Proxy for qBittorrent: Complete Technical Guide

> Master qBittorrent's SOCKS5 proxy settings. This comprehensive guide details configuration using Net::ProxyConfigurationManager for enhanced privacy and security.

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

---

**qBittorrent implements SOCKS5 proxy support through the `Net::ProxyConfigurationManager` singleton, which persists configuration in Qt's `QSettings` under the `Network/Proxy/` key prefix and broadcasts updates via the `proxyConfigurationChanged()` signal to all networking subsystems.**

The `qbittorrent/qBittorrent` repository centralizes proxy handling inside the base networking layer, allowing both GUI users and developers to route BitTorrent peer traffic, RSS feeds, and HTTP requests through SOCKS4 or SOCKS5 proxies. The architecture relies on a type-safe configuration structure and a persistent manager that decouples UI settings from the underlying socket implementations.

## How qBittorrent Handles Proxy Configuration

The proxy subsystem revolves around three core components defined in the `src/base/net/` directory.

**`Net::ProxyType`** (defined in [`src/base/net/proxytype.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/net/proxytype.h)) is an enum that declares the supported protocols:

- `Net::ProxyType::None`
- `Net::ProxyType::SOCKS4`
- `Net::ProxyType::SOCKS5`
- `Net::ProxyType::HTTP`

**`Net::ProxyConfiguration`** (declared in [`src/base/net/proxyconfigurationmanager.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/net/proxyconfigurationmanager.h)) is a plain struct holding the runtime parameters: IP address, port, authentication credentials (`username`, `password`), and flags for `authEnabled` and `hostnameLookupEnabled`.

**`Net::ProxyConfigurationManager`** (implemented in [`src/base/net/proxyconfigurationmanager.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/net/proxyconfigurationmanager.cpp)) is a singleton that owns the active `ProxyConfiguration` instance. It handles persistence through the `SETTINGS_KEY` macro (resolving to `Network/Proxy/`) and emits `proxyConfigurationChanged()` whenever the configuration mutates. Subsystems such as `BitTorrent::Session`, the RSS fetcher, and the Web UI connect to this signal to reinitialize their socket factories immediately.

## Configuring SOCKS5 via the GUI

Follow these steps to enable SOCKS5 through the Options dialog:

1. Open **Tools → Options** (or press **Alt+O**).
2. Navigate to the **Connection** tab.
3. In the **Proxy** section:
   - Select **SOCKS5** from the *Proxy type* drop-down.  
     The UI populates this list in `OptionsDialog::loadConnectionTabOptions()` at lines 34–38 of [`src/gui/optionsdialog.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/gui/optionsdialog.cpp):
     ```cpp
     m_ui->comboProxyType->addItem(tr("(None)"), QVariant::fromValue(Net::ProxyType::None));
     m_ui->comboProxyType->addItem(tr("SOCKS4"), QVariant::fromValue(Net::ProxyType::SOCKS4));
     m_ui->comboProxyType->addItem(tr("SOCKS5"), QVariant::fromValue(Net::ProxyType::SOCKS5));
     m_ui->comboProxyType->addItem(tr("HTTP"),   QVariant::fromValue(Net::ProxyType::HTTP));
     ```

   - Enter the *IP address* and *Port* (commonly 1080).
   - Enable **Authentication** and supply *Username* and *Password* if your proxy requires credentials.
   - Optionally check **Hostname lookup through proxy** to resolve DNS remotely.
4. Select which traffic to route:
   - *Use proxy for BitTorrent traffic* – peer connections.
   - *Use proxy for RSS feeds* – RSS fetcher.
   - *Use proxy for general purposes* – Web UI and tracker announcements.
5. Click **Apply** or **OK**.

When you save, `OptionsDialog::saveConnectionTabOptions()` calls `ProxyConfigurationManager::setProxyConfiguration()`, which writes to persistent storage (lines 91–104 of [`proxyconfigurationmanager.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/proxyconfigurationmanager.cpp)) and emits the change signal. All listeners update their socket factories without requiring a restart.

## Configuring SOCKS5 Programmatically

To manipulate proxy settings from a plugin, startup script, or custom build, interact directly with the manager:

```cpp
#include "base/net/proxyconfigurationmanager.h"

using namespace Net;

// Retrieve current configuration
const ProxyConfiguration current = ProxyConfigurationManager::instance()->proxyConfiguration();

// Configure a new SOCKS5 proxy
ProxyConfiguration cfg;
cfg.type = ProxyType::SOCKS5;
cfg.ip = u"127.0.0.1"_s;          // QString literal
cfg.port = 1080;
cfg.authEnabled = true;
cfg.username = u"user"_s;
cfg.password = u"pass"_s;
cfg.hostnameLookupEnabled = true;

// Apply and broadcast
ProxyConfigurationManager::instance()->setProxyConfiguration(cfg);
// signal proxyConfigurationChanged() fires automatically

```

The `setProxyConfiguration()` method updates both the in-memory struct and the backing `QSettings` under the `Network/Proxy/` hierarchy. Any component holding a pointer to the manager will receive the signal and reconfigure its sockets accordingly.

## Selecting Traffic Types for Proxy Routing

Setting the proxy is only half the configuration; you must also enable it for specific subsystems. In the GUI, this corresponds to the three checkboxes under the proxy fields. In code, set these boolean preference values (as seen in `saveConnectionTabOptions()` at lines 41–45 of [`optionsdialog.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/optionsdialog.cpp)):

```cpp
Preferences::instance()->setUseProxyForBT(true);              // Peer connections
Preferences::instance()->setUseProxyForRSS(true);             // RSS feeds
Preferences::instance()->setUseProxyForGeneralPurposes(true); // Web UI & trackers

```

If these flags remain disabled, qBittorrent continues to use direct connections for those traffic types even when a SOCKS5 proxy is configured in the manager.

## Summary

- **Centralized Management:** All SOCKS5 settings flow through `Net::ProxyConfigurationManager`, a singleton that exposes `setProxyConfiguration()` and the `proxyConfigurationChanged()` signal.
- **Persistent Storage:** Configuration survives restarts because the manager serializes to Qt `QSettings` under the `Network/Proxy/` prefix.
- **Traffic Scoping:** You must explicitly enable proxy usage for BitTorrent peers, RSS, and general HTTP via separate preference flags.
- **Source Locations:** Core logic resides in [`src/base/net/proxyconfigurationmanager.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/net/proxyconfigurationmanager.cpp) and [`src/base/net/proxytype.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/net/proxytype.h), while the UI glue is in [`src/gui/optionsdialog.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/gui/optionsdialog.cpp).

## Frequently Asked Questions

### Does qBittorrent support SOCKS5 authentication?

Yes. The `Net::ProxyConfiguration` struct includes `authEnabled`, `username`, and `password` fields. When `authEnabled` is true, qBittorrent transmits the credentials during the SOCKS5 handshake. Set these values in the GUI by checking **Authentication** or programmatically via the configuration struct before calling `setProxyConfiguration()`.

### Where does qBittorrent store SOCKS5 proxy settings on disk?

Settings persist through Qt’s `QSettings` mechanism under the key prefix `Network/Proxy/`. On Linux, this typically maps to `$HOME/.config/qBittorrent/qBittorrent.conf`; on Windows, to the registry or an INI file depending on the portable mode. The `ProxyConfigurationManager` abstracts the exact storage path through the `SettingValue` template.

### Why are my peer connections not using the SOCKS5 proxy after configuration?

Proxy settings and traffic routing are independent. You must enable *Use proxy for BitTorrent traffic* in the GUI (or call `Preferences::instance()->setUseProxyForBT(true)` in code). Without this flag, the `BitTorrent::Session` continues to initiate direct peer connections even when a proxy is configured in the manager.

### Can I configure a SOCKS5 proxy without opening the qBittorrent GUI?

Yes. Any code linked against the qBittorrent base library can obtain the `ProxyConfigurationManager` singleton and invoke `setProxyConfiguration()`. This allows headless setups, automated deployment scripts, or third-party wrappers to inject proxy settings before the BitTorrent session initializes. Ensure you also set the traffic-type preference flags (BT, RSS, General) to actually route data through the proxy.