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

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.

// 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.

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

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:

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

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

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

The option is defined in src/app/cmdoptions.cpp (line 327) as a BoolOption:

// 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 serves as the bridge to libtorrent. The setter toggles flags on the native handle and updates cached status:

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

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

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.

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