# How to Create Torrent Files with qBittorrent: GUI, C++, and API Methods

> Learn how to create torrent files with qBittorrent using its GUI, C++ API, or Web API. Understand the technical process behind torrent creation.

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

---

**qBittorrent creates torrent files through a multi-threaded architecture where the **TorrentCreatorDialog** collects user input, the **TorrentCreator** class (a **QRunnable** task) performs the heavy lifting in background threads, and the **Web API** exposes the same functionality via HTTP POST requests to `/api/v2/torrents/create`.**

The qbittorrent/qBittorrent repository provides three distinct ways to generate `.torrent` metadata files: through the desktop client’s interface, programmatically via C++ using the core library classes, or remotely through the built-in Web API. Each method relies on the same underlying infrastructure defined in [`src/base/bittorrent/torrentcreator.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/torrentcreator.h) and [`src/base/bittorrent/torrentcreator.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/torrentcreator.cpp).

## Architecture Overview: How qBittorrent Creates Torrents

The torrent creation workflow follows a strict separation between the user interface and core logic to keep the application responsive:

1. **Entry Point**: The `MainWindow` class in [`src/gui/mainwindow.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/gui/mainwindow.cpp) (line 1254) instantiates `TorrentCreatorDialog` when the user selects **File → Create Torrent...**
2. **Parameter Collection**: The dialog populates a `BitTorrent::TorrentCreatorParams` struct with the source path, piece size, private flag, trackers, web seeds, comment, and alignment settings.
3. **Piece Calculation**: Clicking "Calculate total pieces" spawns a `PieceCalculationThread` that invokes the static method `BitTorrent::TorrentCreator::calculateTotalPieces` to preview the piece count without blocking the main thread.
4. **Background Processing**: When the user confirms, the dialog constructs a `BitTorrent::TorrentCreator` object (which inherits from `QRunnable`) and submits it to a `QThreadPool` via `m_threadPool.start(torrentCreator)`.
5. **Signal-Based Updates**: The creator emits `progressUpdated`, `creationSuccess`, and `creationFailure` signals, which the dialog handles via `updateProgressBar`, `handleCreationSuccess`, and `handleCreationFailure` slots.
6. **Post-Creation Seeding**: On success, `handleCreationSuccess` reads the `TorrentCreatorResult`, builds an `AddTorrentParams` structure, and asks the global `BitTorrent::Session` singleton to add the torrent to the transfer list if "Start seeding" is enabled.

## Method 1: Creating Torrent Files Using the GUI

To create a torrent interactively:

1. Open qBittorrent and choose **File → Create Torrent...** (or click the toolbar button). This action is defined in [`src/gui/mainwindow.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/gui/mainwindow.cpp) at line 1254.
2. In the **TorrentCreatorDialog**, select the file or folder you want to share.
3. Choose a **piece size** or leave it on "Auto" (mapped to `pieceSize = 0` in `TorrentCreatorParams`).
4. Enter **tracker URLs** (one per line) and optional **web seeds**.
5. Toggle **private**, add a **comment**, or specify a **source** string as needed.
6. Click **Calculate total pieces** to preview the piece count via `PieceCalculationThread`.
7. Click **Create Torrent**, choose the destination path for the `.torrent` file, and confirm.
8. Check **Start seeding** to have `BitTorrent::Session` automatically add the torrent to your transfer list immediately after generation.

## Method 2: Creating Torrents Programmatically with C++

You can invoke the same logic from custom plugins or Qt applications by using the core classes directly:

```cpp
#include <base/bittorrent/torrentcreator.h>
#include <base/bittorrent/torrentcreationtask.h>
#include <base/bittorrent/torrentcreationmanager.h>
#include <base/path.h>

using namespace BitTorrent;

// 1. Fill the parameters
TorrentCreatorParams params;
params.sourcePath = Path(u"/home/user/my_folder");               // file or directory
params.torrentFilePath = Path(u"/home/user/my_folder.torrent"); // where to write the .torrent
params.pieceSize = 0;                                          // 0 → auto (Qt UI uses "Auto")
params.isPrivate = false;
params.trackers = {u"udp://tracker.openbittorrent.com:80/announce"};
params.urlSeeds = {};                                          // optional web seeds
params.comment = u"This is a demo torrent";
params.source = u"qBittorrent demo";

// 2. Create the creator object (QRunnable)
auto *creator = new TorrentCreator(params);

// 3. Connect to signals (optional – for progress feedback)
QObject::connect(creator, &TorrentCreator::progressUpdated,
                 [](int perc) { qDebug() << "Progress:" << perc << "%"; });
QObject::connect(creator, &TorrentCreator::creationSuccess,
                 [](const TorrentCreatorResult &res) {
                     qDebug() << "Torrent created at:" << res.torrentFilePath;
                 });
QObject::connect(creator, &TorrentCreator::creationFailure,
                 [](const QString &msg) { qWarning() << "Failed:" << msg; });

// 4. Run it in a thread pool (the same pool used by the UI)
static QThreadPool pool;
pool.start(creator);   // `creator` will delete itself after finishing

```

**Explanation**: The `TorrentCreatorParams` struct mirrors exactly what the GUI gathers. Because `TorrentCreator` implements `QRunnable::run()`, submitting it to a `QThreadPool` prevents UI blocking. The creator writes the final `.torrent` file to `params.torrentFilePath` and emits `creationSuccess` containing a `TorrentCreatorResult` struct with the final path, save directory, and piece size used.

## Method 3: Creating Torrents via the Web API

The embedded Web UI exposes torrent creation through a REST endpoint. Send a POST request to:

```

POST /api/v2/torrents/create

```

Include form fields matching `TorrentCreatorParams` such as `savepath`, `url`, `trackers`, `comment`, `private`, and `piece_size`. The implementation resides in [`src/webui/api/torrentcreatorcontroller.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/webui/api/torrentcreatorcontroller.cpp), which validates the input, constructs a `TorrentCreatorParams` object, and delegates to the same `TorrentCreator` class used by the desktop GUI.

## Key Classes and Source Files

| Class | Purpose | File |
|-------|---------|------|
| **TorrentCreatorDialog** | UI widget that gathers user input and orchestrates the creation job. | [`src/gui/torrentcreatordialog.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/gui/torrentcreatordialog.h)<br>[`src/gui/torrentcreatordialog.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/gui/torrentcreatordialog.cpp) |
| **TorrentCreator** | Core logic that generates the `.torrent` file using libtorrent; implements `QRunnable` for thread-pool execution. | [`src/base/bittorrent/torrentcreator.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/torrentcreator.h)<br>[`src/base/bittorrent/torrentcreator.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/torrentcreator.cpp) |
| **TorrentCreatorParams** | Plain-old-data struct holding all creation options (paths, trackers, flags). | [`src/base/bittorrent/torrentcreator.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/torrentcreator.h) |
| **TorrentCreatorResult** | Struct returned on success containing the final torrent path and metadata. | [`src/base/bittorrent/torrentcreator.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/torrentcreator.h) |
| **TorrentCreatorController** | Web API handler that exposes creation via HTTP. | [`src/webui/api/torrentcreatorcontroller.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/webui/api/torrentcreatorcontroller.h)<br>[`src/webui/api/torrentcreatorcontroller.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/webui/api/torrentcreatorcontroller.cpp) |
| **Session** | Global singleton that handles post-creation seeding when requested. | [`src/base/bittorrent/session.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/session.h) |

## Summary

- **Launch the dialog** via `MainWindow` at line 1254 in [`src/gui/mainwindow.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/gui/mainwindow.cpp) to trigger the GUI workflow.
- **Background execution** is handled by submitting a `TorrentCreator` instance to `QThreadPool`, preventing interface freezes.
- **Configure parameters** using the `TorrentCreatorParams` struct and preview piece counts with `TorrentCreator::calculateTotalPieces`.
- **Enable immediate seeding** by having `BitTorrent::Session` process the result after `handleCreationSuccess` emits.
- **Automate via API** using the `/api/v2/torrents/create` endpoint implemented in [`src/webui/api/torrentcreatorcontroller.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/webui/api/torrentcreatorcontroller.cpp).

## Frequently Asked Questions

### How do I calculate the total number of pieces before creating the torrent?

The GUI spawns a `PieceCalculationThread` that calls the static method `BitTorrent::TorrentCreator::calculateTotalPieces` defined in [`src/base/bittorrent/torrentcreator.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/torrentcreator.cpp). This runs the same sizing algorithm used during actual creation to preview how many pieces will be generated based on your content size and selected piece size.

### Can I start seeding immediately after creating a torrent file?

Yes. When `TorrentCreator` emits the `creationSuccess` signal, the dialog’s `handleCreationSuccess` slot (in [`src/gui/torrentcreatordialog.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/gui/torrentcreatordialog.cpp)) reads the `TorrentCreatorResult`, constructs an `AddTorrentParams` object, and passes it to the global `BitTorrent::Session` singleton. Enable the "Start seeding" checkbox in the GUI or set the equivalent flag in the API request.

### Is it possible to create torrents from the command line?

While qBittorrent is primarily a GUI application, you can automate creation via the **Web API** by sending a POST request to `/api/v2/torrents/create` with URL-encoded parameters matching `TorrentCreatorParams`. Alternatively, link against the qBittorrent base library and use the C++ snippet above in your own Qt-based CLI tool.

### What parameters can I configure when creating a torrent?

The `TorrentCreatorParams` struct in [`src/base/bittorrent/torrentcreator.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/torrentcreator.h) exposes: `sourcePath` (file or folder), `torrentFilePath` (destination), `pieceSize` (0 for auto), `isPrivate` (boolean), `trackers` (list of URLs), `urlSeeds` (web seeds), `comment`, `source`, and alignment options. These map directly to the input fields in the `TorrentCreatorDialog`.