# How to Enable Sequential Downloading in qBittorrent: GUI, Web API, and CLI Methods

> Learn to enable sequential downloading in qBittorrent using the GUI, Web API, or CLI for faster torrent streaming and early access to content.

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

---

**You can enable sequential downloading in qBittorrent by toggling "Download in sequential order" from the transfer list context menu, torrent options dialog, Web API (`sequentialDownload=true`), or CLI (`--sequential`), which internally sets the libtorrent `sequential_download` flag via `TorrentImpl::setSequentialDownload()`.**

Sequential downloading forces qBittorrent to request pieces in first-to-last order rather than the rarest-first default, enabling video streaming while files are still incomplete. This feature is implemented across the entire application stack—from the Qt6 GUI to the JSON-RPC API—ultimately translating to the `lt::torrent_flags::sequential_download` flag in the underlying libtorrent library. Whether you are using the desktop client, automating downloads via the Web UI, or running headless with qbittorrent-nox, the setting persists across restarts via resume data.

## What Is Sequential Downloading?

Sequential downloading alters the piece selection strategy in BitTorrent. Instead of downloading the rarest pieces first (the standard swarm-friendly approach), the client requests pieces sequentially from the beginning of the file. This is particularly useful when you need deterministic file boundaries for media playback or when preparing archives for sequential access.

## Enabling Sequential Downloading via the GUI

The qBittorrent GUI provides two primary interfaces for toggling sequential mode: the transfer list context menu and the torrent options dialog.

### Transfer List Context Menu

Right-click any torrent in the transfer list and select **"Download in sequential order"**. This action creates a `TriStateAction` widget that supports batch toggling when multiple torrents are selected.

```cpp
// src/gui/transferlistwidget.cpp (lines 12424-12427)
auto *actionSequentialDownload = new TriStateAction(tr("Download in sequential order"), listMenu);
connect(actionSequentialDownload, &QAction::triggered, this,
        &TransferListWidget::setSelectedTorrentsSequentialDownload);

```

When triggered, `setSelectedTorrentsSequentialDownload()` iterates through selected torrents and calls `setSequentialDownload()` on each `BitTorrent::Torrent` object.

### Torrent Options Dialog

Double-click a torrent or select **"Torrent options..."** from the context menu to open the dialog. The **"Download in sequential order"** checkbox appears as a tri-state control (supporting partial selection states) mapped to `m_ui->checkSequential`.

```cpp
// src/gui/torrentoptionsdialog.cpp (line 371)
.sequential = m_ui->checkSequential->checkState(),

// Applied when the dialog is accepted (line 491)
torrent->setSequentialDownload(m_ui->checkSequential->isChecked());

```

## Enabling Sequential Downloading via the Web API

The Web UI exposes sequential downloading through the `/api/v2/torrents/add` endpoint using the `sequentialDownload` parameter, and reflects the current state via the `seq_dl` field in sync responses.

When adding a torrent via RPC:

```http
POST /api/v2/torrents/add HTTP/1.1
Content-Type: application/x-www-form-urlencoded

urls=http://example.com/file.torrent&sequentialDownload=true

```

The controller parses this parameter at line 1077 of [`src/webui/api/torrentscontroller.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/webui/api/torrentscontroller.cpp):

```cpp
// src/webui/api/torrentscontroller.cpp
const bool seqDownload = parseBool(params()[u"sequentialDownload"_s]).value_or(false);
// ...
addTorrentParams.sequential = seqDownload,

```

The current state is exposed to web clients through the sync controller:

```cpp
// src/webui/api/synccontroller.cpp
// "seq_dl": Torrent sequential download state (line 485)

```

## Enabling Sequential Downloading via Command Line

For headless operations using `qbittorrent-nox`, append the `--sequential` flag when adding torrents:

```bash
qbittorrent-nox --add /path/to/file.torrent --sequential

```

The option is defined in [`src/app/cmdoptions.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/app/cmdoptions.cpp) (line 327) as a `BoolOption`:

```cpp
// src/app/cmdoptions.cpp (line 327)
constexpr const BoolOption SEQUENTIAL_OPTION {u"sequential"};

// Usage description (lines 405-406)
+ SEQUENTIAL_OPTION.usage() + wrapText(QCoreApplication::translate("CMD Options",
 "Download files in sequential order")) + u'\n'

```

When parsed, the value is stored in `addTorrentParams.sequential` (line 441) and later processed by the application during torrent construction.

## Technical Implementation Details

Understanding the core implementation helps when developing plugins or debugging download behavior.

### Core Logic in torrentimpl.cpp

The `TorrentImpl` class in [`src/base/bittorrent/torrentimpl.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/torrentimpl.cpp) serves as the bridge to libtorrent. The setter toggles flags on the native handle and updates cached status:

```cpp
// src/base/bittorrent/torrentimpl.cpp (lines 1724-1733)
void TorrentImpl::setSequentialDownload(const bool enable)
{
    if (enable) {
        m_nativeHandle.set_flags(lt::torrent_flags::sequential_download);
        m_nativeStatus.flags |= lt::torrent_flags::sequential_download;
    } else {
        m_nativeHandle.unset_flags(lt::torrent_flags::sequential_download);
        m_nativeStatus.flags &= ~lt::torrent_flags::sequential_download;
    }
    deferredRequestResumeData();
}

```

The query method reads from cached flags:

```cpp
// src/base/bittorrent/torrentimpl.cpp (lines 1268-1269)
bool TorrentImpl::isSequentialDownload() const
{
    return static_cast<bool>(m_nativeStatus.flags & lt::torrent_flags::sequential_download);
}

```

### Session Integration and libtorrent

When adding new torrents, `SessionImpl` prepares the `add_torrent_params` structure (lines 23-26 of [`src/base/bittorrent/sessionimpl.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/sessionimpl.cpp)):

```cpp
if (addTorrentParams.sequential)
    p.flags |= lt::torrent_flags::sequential_download;
else
    p.flags &= ~lt::torrent_flags::sequential_download;

```

This ensures the flag is set at the moment libtorrent begins the download, avoiding piece selection conflicts.

### State Persistence Across Restarts

The call to `deferredRequestResumeData()` inside `setSequentialDownload()` schedules an asynchronous write to the resume file. This stores the flag in the fastresume data, ensuring that if qBittorrent restarts, the torrent resumes in sequential mode without requiring user intervention.

## Summary

- **GUI methods**: Use the transfer list context menu (**"Download in sequential order"**) or the torrent options dialog checkbox to toggle `TorrentImpl::setSequentialDownload()`.
- **Web API**: Pass `sequentialDownload=true` when posting to `/api/v2/torrents/add`; monitor status via the `seq_dl` JSON field.
- **CLI**: Use the `--sequential` flag with `qbittorrent-nox --add` to set the option at launch.
- **Core mechanism**: All interfaces funnel to `TorrentImpl::setSequentialDownload()`, which manipulates `lt::torrent_flags::sequential_download` on the native libtorrent handle.
- **Persistence**: Changes are written to resume data via `deferredRequestResumeData()`, surviving application restarts.

## Frequently Asked Questions

### Does enabling sequential downloading affect download speed?

Sequential downloading can reduce overall swarm efficiency because you are no longer prioritizing rare pieces. However, for well-seeded torrents or when download order matters more than speed (such as media streaming), the impact is negligible. The libtorrent documentation notes that sequential mode may also reduce the effectiveness of end-game mode piece picking.

### How can I verify that sequential downloading is active for a specific torrent?

In the GUI, check the torrent options dialog—the **"Download in sequential order"** checkbox will reflect the current state. Via the Web API, query the sync endpoint and inspect the `seq_dl` boolean field in the torrent object. Internally, this reads `TorrentImpl::isSequentialDownload()`, which checks `m_nativeStatus.flags & lt::torrent_flags::sequential_download`.

### Is the sequential download setting preserved after I restart qBittorrent?

Yes. When you toggle sequential mode, `TorrentImpl::setSequentialDownload()` immediately calls `deferredRequestResumeData()`, which schedules a write to the fastresume file. Upon restart, `SessionImpl` reads this resume data and reconstructs the torrent with the appropriate flags set in `add_torrent_params`.

### Can I enable sequential downloading for multiple torrents simultaneously?

Yes. The transfer list context menu supports batch operations through `TransferListWidget::setSelectedTorrentsSequentialDownload()`. Select multiple torrents (Ctrl+Click or Shift+Click), right-click, and toggle **"Download in sequential order"**. The tri-state checkbox in the torrent options dialog also supports partial states when selected torrents have mixed sequential settings.