Configuring SOCKS5 Proxy for qBittorrent: Complete Technical Guide

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) 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) 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) 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:

     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) 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:

#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):

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 and src/base/net/proxytype.h, while the UI glue is in 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.

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