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

> Learn how to configure bandwidth limits in qBittorrent with this complete technical guide. Master global and alternative speed limits for optimal torrenting.

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

---

**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`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/session.h), the pure virtual interface declares these methods:

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

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

```

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

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

```

Set upload limit to 500 KiB/s:

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

```

Enable alternative speed limits programmatically:

```bash
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`](https://github.com/qbittorrent/qBittorrent/blob/main/base/bittorrent/session.h) and access the singleton:

```cpp
#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`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/session.h) — Public API declarations for limit getters/setters
- [`src/base/bittorrent/sessionimpl.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/sessionimpl.cpp) — Concrete implementation forwarding to libtorrent
- [`src/gui/speedlimitdialog.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/gui/speedlimitdialog.cpp) — Desktop GUI dialog logic
- `src/gui/speedlimitdialog.ui` — Qt Designer interface definition
- [`src/base/bittorrent/bandwidthscheduler.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/bandwidthscheduler.cpp) — Time-based automatic switching
- [`src/webui/api/transfercontroller.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/webui/api/transfercontroller.cpp) — HTTP JSON API endpoints
- [`src/webui/www/private/speedlimit.html`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/session.h) and [`src/webui/api/transfercontroller.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/sessionimpl.cpp)), which persists values as member variables and forwards them to libtorrent. The settings are serialized to [`qBittorrent.ini`](https://github.com/qbittorrent/qBittorrent/blob/main/qBittorrent.ini) on disk, but runtime modifications always route through the `Session` singleton methods.