How to Configure Bandwidth Limits in qBittorrent: A Complete Technical Guide

qBittorrent controls bandwidth through the BitTorrent::Session singleton, exposing global and alternative speed limits via the Speed Limit dialog, Web API endpoints, or direct C++ calls to Session methods.

The qBittorrent client manages all throughput restrictions through a centralized session architecture that stores four primary velocity thresholds. Understanding how to configure bandwidth limits in qBittorrent requires navigating the Session API, which propagates constraints to the underlying libtorrent library through multiple front-end interfaces.

Core Architecture of Bandwidth Control

All bandwidth management in qBittorrent originates from the BitTorrent::Session singleton. This class maintains four distinct limit values that govern transfer speeds:

• Global download limit: globalDownloadSpeedLimit() / setGlobalDownloadSpeedLimit(int)
• Global upload limit: globalUploadSpeedLimit() / setGlobalUploadSpeedLimit(int)
• Alternative download limit: altGlobalDownloadSpeedLimit() / setAltGlobalDownloadSpeedLimit(int)
• Alternative upload limit: altGlobalUploadSpeedLimit() / setAltGlobalUploadSpeedLimit(int)

These limits function as ** KiB/s** (kilobytes per second) values where zero typically indicates unlimited bandwidth. The Session interface also provides isAltGlobalSpeedLimitEnabled() and setAltGlobalSpeedLimitEnabled(bool) to toggle between standard and alternative speed profiles.

In src/base/bittorrent/session.h, the pure virtual interface declares these methods:

virtual int globalDownloadSpeedLimit() const = 0;
virtual void setGlobalDownloadSpeedLimit(int limit) = 0;
virtual int globalUploadSpeedLimit() const = 0;
virtual void setGlobalUploadSpeedLimit(int limit) = 0;
virtual int altGlobalDownloadSpeedLimit() const = 0;
virtual void setAltGlobalDownloadSpeedLimit(int limit) = 0;
virtual int altGlobalUploadSpeedLimit() const = 0;
virtual void setAltGlobalUploadSpeedLimit(int limit) = 0;

The concrete implementation in SessionImpl forwards these calls to libtorrent's session object, ensuring the constraints apply at the protocol level.

Desktop GUI Configuration

The SpeedLimitDialog class provides the primary graphical interface for adjusting bandwidth constraints. Located in src/gui/speedlimitdialog.cpp, this dialog reads current values from the session instance and writes modifications back when accepted.

To configure limits through the GUI:

1. Open Tools → Options → Speed Limits or press Ctrl+S.
2. Adjust the Global download limit and Global upload limit sliders (values in KiB/s).
3. Check Alternative speed limits to enable the secondary profile.
4. Set the alternative download and upload thresholds for scheduled restrictions.
5. Click OK to invoke SpeedLimitDialog::accept(), which calls the session setters.

The dialog automatically synchronizes with the session state because Session emits change signals that the UI observes, ensuring real-time consistency between multiple configuration vectors.

Scheduled Bandwidth Management

The BandwidthScheduler class in src/base/bittorrent/bandwidthscheduler.cpp enables automatic switching between global and alternative limits based on time schedules. When active, the scheduler emits the bandwidthLimitRequested(bool alternative) signal.

SessionImpl connects to this signal and calls setAltGlobalSpeedLimitEnabled(true) or setAltGlobalSpeedLimitEnabled(false) depending on the current time relative to your configured schedule. This mechanism allows automatic throttling during peak hours without manual intervention.

Web UI API Configuration

Remote configuration utilizes the TransferController in src/webui/api/transfercontroller.cpp, which exposes JSON endpoints that map directly to session methods:

Endpoint	Method	Description
GET /api/v2/transfer/info	—	Returns current rates and configured limits
POST /api/v2/transfer/setDownloadLimit	setDownloadLimit	Sets global download limit (KiB/s)
POST /api/v2/transfer/setUploadLimit	setUploadLimit	Sets global upload limit (KiB/s)
POST /api/v2/transfer/toggleSpeedLimitsMode	—	Toggles alternative mode
POST /api/v2/transfer/setSpeedLimitsMode	—	Sets alternative mode (0 or 1)

Practical cURL Examples

Retrieve current configuration:

curl -s http://localhost:8080/api/v2/transfer/info

Set global download limit to 2 MiB/s (2048 KiB/s):

curl -X POST -d "limit=2048" http://localhost:8080/api/v2/transfer/setDownloadLimit

Set upload limit to 500 KiB/s:

curl -X POST -d "limit=500" http://localhost:8080/api/v2/transfer/setUploadLimit

Enable alternative speed limits programmatically:

curl -X POST -d "mode=1" http://localhost:8080/api/v2/transfer/setSpeedLimitsMode

Programmatic C++ Configuration

For plugin development or custom builds, direct manipulation of the Session instance provides the most efficient configuration path. Include base/bittorrent/session.h and access the singleton:

#include "base/bittorrent/session.h"

void configureBandwidthLimits()
{
    // Set global limits in KiB/s
    BitTorrent::Session::instance()->setGlobalDownloadSpeedLimit(2048); // 2 MiB/s
    BitTorrent::Session::instance()->setGlobalUploadSpeedLimit(512);     // 512 KiB/s

    // Configure alternative limits for scheduled periods
    BitTorrent::Session::instance()->setAltGlobalDownloadSpeedLimit(1024); // 1 MiB/s
    BitTorrent::Session::instance()->setAltGlobalUploadSpeedLimit(256);     // 256 KiB/s

    // Activate alternative mode immediately
    BitTorrent::Session::instance()->setAltGlobalSpeedLimitEnabled(true);
}

Changes propagate immediately to active torrents because SessionImpl updates the underlying libtorrent session settings without requiring restarts.

Key Source Files Reference

The complete bandwidth limit implementation spans these critical files:

• src/base/bittorrent/session.h — Public API declarations for limit getters/setters
• src/base/bittorrent/sessionimpl.cpp — Concrete implementation forwarding to libtorrent
• src/gui/speedlimitdialog.cpp — Desktop GUI dialog logic
• src/gui/speedlimitdialog.ui — Qt Designer interface definition
• src/base/bittorrent/bandwidthscheduler.cpp — Time-based automatic switching
• src/webui/api/transfercontroller.cpp — HTTP JSON API endpoints
• src/webui/www/private/speedlimit.html — Web interface frontend

Summary

• qBittorrent stores bandwidth limits in the BitTorrent::Session singleton as KiB/s integers via setGlobalDownloadSpeedLimit() and companion methods.
• Three configuration interfaces exist: the SpeedLimitDialog GUI (Ctrl+S), the Web UI REST API (/api/v2/transfer/*), and direct C++ calls to Session::instance().
• Alternative limits provide scheduled throttling when enabled through setAltGlobalSpeedLimitEnabled(), typically managed automatically by BandwidthScheduler.
• Source file locations in src/base/bittorrent/session.h and src/webui/api/transfercontroller.cpp demonstrate the complete path from user input to libtorrent enforcement.

Frequently Asked Questions

What is the difference between global and alternative speed limits in qBittorrent?

Global limits represent your default bandwidth constraints applied continuously, while alternative limits function as a secondary profile activated manually or automatically via the scheduler. The BitTorrent::Session class tracks both sets independently, switching between them when setAltGlobalSpeedLimitEnabled(bool) toggles the active mode.

How do I enable scheduled bandwidth limiting?

Enable scheduling in Tools → Options → Speed → Alternative rate limits and define the time periods. The BandwidthScheduler class monitors these schedules and emits bandwidthLimitRequested(true) when entering a restricted period, causing SessionImpl to activate alternative limits automatically.

Can I configure bandwidth limits via command line without the GUI?

Yes, through the Web UI API using HTTP requests. While qBittorrent lacks a native CLI configuration tool, you can script curl commands targeting endpoints like /api/v2/transfer/setDownloadLimit to adjust limits programmatically without launching the graphical interface.

Where does qBittorrent store bandwidth limit values in the source code?

The authoritative storage exists in the BitTorrent::SessionImpl class (defined in src/base/bittorrent/sessionimpl.cpp), which persists values as member variables and forwards them to libtorrent. The settings are serialized to qBittorrent.ini on disk, but runtime modifications always route through the Session singleton methods.

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