Skip to content

qBittorrent

What it is

qBittorrent is a cross-platform, open-source BitTorrent client written in C++. It provides a familiar user interface similar to µTorrent but is entirely free of advertisements and bloatware.

What problem it solves

It provides a reliable and efficient way to download and share files via the BitTorrent protocol. It centralizes torrent management through a powerful web interface, allowing for headless operation on servers or NAS devices.

Where it fits in the stack

Category: Services / Content Acquisition. It is typically part of the "Automation" and "Data Intake" layer of a homelab media stack.

Typical use cases

  • Downloading Linux ISOs and other large open-source datasets.
  • Managing torrents remotely via a web browser.
  • Automating downloads using tools like n8n or the "Arr" suite.
  • Hosting a private seeding box for community-shared content.

Strengths

  • No Ads: Completely free and open-source with no bundled software.
  • Web UI: Excellent, feature-rich web interface that mirrors the desktop application. Now with virtual list rendering for high-performance scrolling in large libraries (v5.2+).
  • Search Engine: Integrated search engine for finding torrents across multiple sites.
  • Resource Efficient: Low CPU and memory footprint. v5.2+ introduces Asynchronous Piece Calculation, keeping the UI responsive even when adding massive torrents.

New in v5.2.x (May 2026)

  • Category-Level Share Limits: Set seeding ratio and time limits per category (e.g., different rules for Movies vs. TV Shows).
  • Unconditional Subcategories: Subcategory support is now permanently enabled, allowing for deeper organizational hierarchies.
  • Free Disk Space Display: The status bar now shows real-time free disk space on the download drive.
  • Enhanced WebUI: Added a Torrent Creator, tracker status filters, and bulk tracker management directly in the browser.
  • Modern Infrastructure: Transitioned to Qt 6.10.3 and Boost 1.86/1.91 for improved stability and performance.

Limitations

  • Security: Requires careful configuration (VPN/Proxy) for private operation.
  • UI Design: The interface is functional but may feel dated to some users.

When to use it

  • When you need a reliable, lightweight BitTorrent client with a web interface.
  • When you want to manage torrents remotely via a browser or API.
  • When you require features like RSS feed support, a download scheduler, and sequential downloading.

When not to use it

  • When you need a client for a protocol other than BitTorrent.
  • When you prefer a client with a more modern, single-page application UI (though qBittorrent's UI is very functional).

Getting started

Docker

The recommended way to run qBittorrent is using the LinuxServer.io image:

docker run -d \
  --name=qbittorrent \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e WEBUI_PORT=8080 \
  -p 8080:8080 \
  -p 6881:6881 \
  -p 6881:6881/udp \
  -v /path/to/appdata/config:/config \
  -v /path/to/downloads:/downloads \
  --restart unless-stopped \
  lscr.io/linuxserver/qbittorrent:latest

Access the web interface at http://localhost:8080. The default credentials (if not printed to the log) are often admin / adminadmin.

Hello World

  1. Run the Docker command to start qBittorrent.
  2. Navigate to http://localhost:8080 and log in.
  3. Go to Tools > Options > BitTorrent and enable "Add torrents in Paused state" for safety.
  4. Click the Add Torrent Link button and paste a legal magnet link (e.g., a Linux ISO) to see the client in action.

VPN Killswitch (Gluetun)

To ensure qBittorrent only downloads when connected to a VPN, use Gluetun as a network sidecar.

services:
  gluetun:
    image: qmcgaw/gluetun
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - VPN_SERVICE_PROVIDER=your_provider
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=your_key
      - WIREGUARD_ADDRESSES=10.0.0.2/32
    ports:
      - 8080:8080 # qBittorrent Web UI

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    network_mode: "container:gluetun"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - WEBUI_PORT=8080
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    restart: unless-stopped

CLI examples

The qbittorrent-nox binary can be managed via the Docker container.

# View container logs to find the temporary WebUI password
docker logs qbittorrent

# Check the version of qBittorrent running in the container
docker exec qbittorrent qbittorrent-nox --version

# Pause all active torrents
docker exec qbittorrent qbittorrent-nox --pause-all

API examples

The Web UI API (v2) allows for remote torrent management.

Python Example

Using the qbittorrent-api library is recommended for Python.

from qbittorrentapi import Client

conn_info = dict(host='localhost', port=8080, username='admin', password='your_password')
qbt_client = Client(**conn_info)

# List all torrents
for torrent in qbt_client.torrents_info():
    print(f"Torrent: {torrent.name}, Progress: {torrent.progress*100:.2f}%")

Curl Example

First, authenticate to get a session cookie:

# Login and save the session cookie
curl -i --header "Referer: http://localhost:8080" \
     --data "username=admin&password=your_password" \
     "http://localhost:8080/api/v2/auth/login"

# List all torrents (requires SID cookie from previous response)
curl "http://localhost:8080/api/v2/torrents/info" \
     --cookie "SID=<your_session_id>"

Licensing and cost

  • Open Source: Yes (GPL-2.0)
  • Cost: Free
  • Self-hostable: Yes

Sources / References

Backlog

  • [x] Perform quarterly technical freshness audit (May 2026).

Contribution Metadata

  • Confidence: high
  • Last reviewed: 2026-05-27