qBittorrent

Feature-rich BitTorrent client with Web UI and integrated search

qBittorrent is a free, open-source BitTorrent client with a clean Qt interface and powerful Web UI for remote administration. QuickBox Pro deploys qBittorrent as the headless qbittorrent-nox binary from QuickBox compiled packages, built with Qt6, libtorrent-rasterbar 2.x, and Boost 1.83+ for maximum performance and compatibility. The installed version is resolved dynamically from the compiled-packages manifest for your distro, so you always get the latest available build.

Web UI

Full-featured web interface via nginx reverse proxy with user-scoped paths

Integrated Search

Built-in search engine with plugin support for finding torrents

Qt6 + libtorrent 2.x

Modern stack compiled with latest Qt6 and libtorrent-rasterbar

RSS Manager

Automated downloads via RSS feeds with smart filters

PBKDF2 Authentication

Secure password hashing using libqbpasswd for Web UI access

Advanced Queueing

Smart torrent queueing with upload/download limits and scheduling

QuickBox Integration Only

qBittorrent should always be managed via the QuickBox CLI (qb) and dashboard. Avoid manual distro package upgrades or editing systemd/nginx files directly.

Installation

Symptoms

QuickBox Pro v3 installed and configured
User account created on the server
Sufficient disk space for torrent data and session files

Resolution

Use QuickBox's qb command for installation
Automatic configuration with reverse proxy
Per-user installation with isolated credentials

Basic Installation

Install qBittorrent for a specific user. The version, along with all dependencies (libtorrent-rasterbar, Boost, Qt6), is resolved automatically from the compiled-packages manifest for your distro:


qb install qbittorrent -u username

CLI Commands

Command	Description
`qb install qbittorrent -u username`	Install qBittorrent (latest available version)
`qb reinstall qbittorrent -u username`	Reinstall while preserving QuickBox integration
`qb update qbittorrent -u username`	Update qBittorrent and all dependencies from compiled packages
`qb remove qbittorrent -u username`	Remove qBittorrent and clean up files
`qb help qbittorrent`	Display comprehensive help information

Dynamic Version Resolution

qBittorrent versions are resolved dynamically from the packages.lst manifest in the QuickBox/compiled-packages repository. The CLI automatically determines the latest available build for your distro codename, along with the matching libtorrent-rasterbar, Boost, and Qt6 dependencies. No manual database updates or version flags are needed.

Branch Channels

QuickBox Pro uses two package channels: main (stable, default) and develop (beta, opt-in). The channel is detected automatically based on your installation. Beta servers may receive newer qBittorrent builds before they are promoted to stable.

CLI Options

-u, --usernameRequired

Target QuickBox username for install/reinstall/remove operations. Supply Admin username for version updates affecting all users.

Automatic Port Assignment

QuickBox automatically assigns the Web UI port starting at 11001 (auto-incremented per user). Find your assigned port in the QuickBox dashboard or in ~/.config/qBittorrent/qBittorrent.conf.

Accessing qBittorrent

After installation, access qBittorrent at:


https://your-server-ip/qbittorrent/

QuickBox Dashboard Integration

qBittorrent is automatically integrated into your QuickBox dashboard. Find it in the Service Control panel with port and status information. Click the LAUNCH icon to open the web interface.

Login credentials:

Username: Your QuickBox username
Password: Your QuickBox password (hashed with PBKDF2)

Browser Download Index

In addition to the qBittorrent Web UI, QuickBox installs a per-user browser file index that lists the contents of your qBittorrent download directory in a dark-themed fancyindex view. Useful for quickly grabbing a single finished file without loading the torrent client.


https://your-server-ip/username.qbittorrent.downloads

How it works

The nginx template at /etc/nginx/software/username.dlindex.conf exposes /home/username/torrents/qbittorrent through the shared fancyindex snippet. Access is protected by auth_basic against /etc/htpasswd.d/htpasswd.username, which is the same credential file used for other QuickBox user endpoints.

The listing path matches the qBittorrent save directory, including the downloads/ and watch/ subfolders.
The index is stitched together per user: if you also have Deluge, rTorrent, or Transmission installed, their .downloads locations are appended into the same username.dlindex.conf so each client gets its own URL.
The feature has no service of its own — it is pure nginx. If the URL returns a 404, verify nginx reloaded after install (systemctl reload nginx) and that /etc/nginx/software/username.dlindex.conf exists.

Initial Configuration

1. Configure Download Paths

Settings → Downloads → Default Save Path: /home/username/torrents/qbittorrent/downloads
Completed torrents can be moved to a different folder automatically
Watch folder configured at /home/username/torrents/qbittorrent/watch

2. Connect to `*arr` Applications (Optional)

If using Sonarr, Radarr, or other *arr applications:

In your *arr app, go to Settings → Download Clients → Add (+)
Select qBittorrent from the list
Enter connection details:
- Host: 127.0.0.1
- Port: Your Web UI port (check ~/.config/qBittorrent/qBittorrent.conf)
- Username: Your QuickBox username
- Password: Your QuickBox password
- Category: Create categories like sonarr, radarr as needed
Test and save

3. Enable Search Plugins (Optional)

Tools → Search → Search plugins → Check for updates
Install plugins for your preferred torrent sites
Search functionality accessible via Web UI

VPN routing for qBittorrent

QuickBox Pro supports routing qBittorrent’s network traffic through a WireGuard VPN tunnel, isolating BitTorrent traffic from the rest of your server’s internet activity. This is managed from System → VPN Control in the dashboard.

Why route qBittorrent through VPN?

Privacy

BitTorrent traffic exits through the VPN, keeping your server's real IP out of swarm peer lists

ISP traffic shaping

Torrent traffic routed through WireGuard is encrypted, preventing ISP throttling of BitTorrent protocol

Kill switch protection

If the VPN tunnel drops, qBittorrent stops sending and receiving — no traffic leaks to your real IP

Traffic isolation

qBittorrent traffic is completely separate from your media servers and other applications on the server

How to enable

Navigate to System → VPN Control in the dashboard (admin access required).
Ensure at least one WireGuard peer configuration is uploaded and active.
Scroll to the App-Scoped Routing card and select qBittorrent.
Enter your Peer Listen Port (see below — this step is required).
Choose a WireGuard peer config from the dropdown.
Click Enable Routing.

Once routing is active, qBittorrent’s traffic exits through the VPN tunnel. The /qbittorrent/ URL and dashboard tile continue to work normally — the dashboard handles internal connectivity automatically.

Peer Listen Port — required step

This port must match qBittorrent's setting

The Peer Listen Port is the port qBittorrent uses to accept incoming connections from other peers in a swarm. The dashboard sets up port forwarding through the VPN tunnel for this port automatically — but only if you tell it which port to use. If the port here does not match what qBittorrent is actually using, peers cannot reach your client. qBittorrent will report a “firewalled” or “not connectable” status, and your connectivity score in swarms will drop significantly on private trackers.

To find or set your peer port in qBittorrent:

Open the qBittorrent Web UI at https://your-server/qbittorrent/.
Go to Settings (gear icon in the top toolbar).
Select the BitTorrent (or Connection) tab.
Under Listening Port, note the port number — or enter a new one in the 1024–65535 range.
Click Save if you changed the port, then restart qBittorrent: systemctl restart qbittorrent@username.
Enter this same port in the VPN Control Peer Listen Port field before clicking Enable Routing.

Changing the peer port later

If you need to change the peer listen port after routing is already enabled, you must disable routing first and then re-enable it with the new port. The port is wired into the routing configuration at enable time.

Kill switch behavior

The kill switch stops qBittorrent if the VPN connection goes stale, ensuring no BitTorrent traffic leaks to your server’s real IP address. The default threshold for qBittorrent is 30 minutes — longer than the 10-minute default for media servers.

This longer default exists because torrent sessions are long-lived. WireGuard handshakes can stall briefly during normal operation (especially on residential-grade VPN providers), and an aggressive threshold would trigger false kill switch events that interrupt active downloads unnecessarily.

You can adjust the threshold between 60 seconds and 24 hours from the kill switch settings panel in VPN Control. When auto-recovery is enabled, the dashboard attempts to restore routing automatically after a kill switch event.

For full VPN Control configuration details — including kill switch tuning and peer management — see the VPN Control documentation.

Service Management

qBittorrent runs as a systemd service for reliability and automatic startup.


systemctl status qbittorrent@username     # Check status
systemctl restart qbittorrent@username    # Restart service
journalctl -u qbittorrent@username -f     # View live logs
systemctl enable qbittorrent@username     # Start on boot
systemctl disable qbittorrent@username    # Prevent auto-start

Troubleshooting

qBittorrent Won’t Start


journalctl -u qbittorrent@username -f

Check for port conflicts:


grep -i 'WebUI\\Port' ~/.config/qBittorrent/qBittorrent.conf
# Default: 11001

Web UI Not Accessible

Symptoms

Cannot access qBittorrent web interface
404 or connection refused errors
Nginx proxy not working

Resolution

Verify service is running: systemctl status qbittorrent@username
Check nginx configuration: /etc/nginx/conf.d/username.qbittorrent.conf
Ensure port is correct in qBittorrent.conf
Reload nginx: systemctl reload nginx

Permission Issues


qb fix permissions -u username
systemctl restart qbittorrent@username

Configuration Reset


# Backup current configuration
cp ~/.config/qBittorrent/qBittorrent.conf ~/.config/qBittorrent/qBittorrent.conf.backup
 
# Remove configuration (will be regenerated)
rm ~/.config/qBittorrent/qBittorrent.conf
 
# Restart service
systemctl restart qbittorrent@username

Best Practices

Do

Use qb update qbittorrent to keep qBittorrent and dependencies updated
Monitor service health with systemctl status qbittorrent@username
Configure RSS feeds and smart filters for automated downloads
Create separate categories for different `*arr` applications
Enable sequential download for media files you want to preview
Use the built-in search engine with updated plugins
Set upload/download limits to manage bandwidth effectively
Configure watch folders for automatic torrent loading

Don't

Don't install qBittorrent from system package managers—use QuickBox packages only
Don't manually edit systemd or nginx configs without backing up first
Don't expose the Web UI directly to the internet without nginx in front
Don't use the same category for multiple `*arr` applications
Don't ignore disk space warnings—qBittorrent may stop downloading
Don't disable DHT/PEX if you use public trackers
Don't set global upload limits too low—may hurt ratio on private trackers
Don't manually edit qBittorrent.conf while the service is running

Use Cases

Automated Media Downloads

Connect to Sonarr, Radarr, Lidarr for automated TV, movie, and music downloads
Category-based organization with automatic file management
Integration with modern *arr stack for complete automation

Manual Torrent Management

Full-featured web interface for adding and managing torrents manually
RSS feed automation for recurring downloads
Search engine integration for finding content directly

Private Tracker Seeding

Advanced ratio management with per-torrent upload limits
Sequential downloading for faster availability
Detailed statistics and tracking for private tracker requirements

FAQ

The CLI resolves the latest available version from the packages.lst manifest in the QuickBox/compiled-packages repository. The manifest is cached locally with a 1-hour TTL and filtered by your distro codename. The matching libtorrent-rasterbar, Boost, and Qt6 dependencies are also resolved automatically.

Currently, the qBittorrent install script always resolves and installs the latest available version from the manifest for your distro. There is no -o version flag for qBittorrent. If you need to stay on a specific version, avoid running qb update qbittorrent.

The main channel (default) contains stable, tested builds. The develop channel (beta) may include newer qBittorrent versions not yet promoted to stable. Your server's channel is detected automatically.

QuickBox compiles qBittorrent with custom builds of libtorrent-rasterbar 2.x, Boost 1.83+, Qt6, and optionally GCC 12+ (on systems with older compilers). All are resolved and installed as precompiled packages from the manifest.

Yes. The Peer Listen Port is required when enabling VPN routing for qBittorrent. It must match the port configured in qBittorrent's own settings (Settings → BitTorrent → Listening Port). The dashboard uses this port to set up forwarding through the VPN tunnel so that remote peers can reach your client. Without it, qBittorrent will appear firewalled to other swarm participants.

If the kill switch is enabled (recommended), qBittorrent stops transferring data when the VPN tunnel goes stale — no torrent traffic leaks to your server's real IP. The default threshold is 30 minutes. If auto-recovery is enabled, the dashboard attempts to restore routing automatically. If not, you can re-enable routing manually from VPN Control once the VPN connection is restored.

Yes. Each routable app gets its own isolated VPN tunnel, so qBittorrent, Emby, Jellyfin, and Plex can all be routed simultaneously — each through the same or different WireGuard peer configurations. Traffic from each app is fully isolated from the others.

Additional Resources

VPN Control

Enable VPN routing for qBittorrent and manage WireGuard peers

WireGuard VPN

Install and configure WireGuard before enabling app-scoped routing

qBittorrent Official Documentation

Official wiki with configuration guides and API documentation

qBittorrent Web API

WebUI API reference for automation and integration

qBittorrent GitHub Repository

Official source code and issue tracking

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support

Feature Previews

Community Configs

Active Discussions

Join Discord Server

qBittorrent

Web UI

Integrated Search

Qt6 + libtorrent 2.x

RSS Manager

PBKDF2 Authentication

Advanced Queueing

Installation

Symptoms

Resolution

Basic Installation

CLI Commands

Dynamic Version Resolution

CLI Options

Accessing qBittorrent

Browser Download Index

Initial Configuration

1. Configure Download Paths

2. Connect to *arr Applications (Optional)

3. Enable Search Plugins (Optional)

VPN routing for qBittorrent

Why route qBittorrent through VPN?

Privacy

ISP traffic shaping

Kill switch protection

Traffic isolation

How to enable

Peer Listen Port — required step

Kill switch behavior

Service Management

Troubleshooting

qBittorrent Won’t Start

Web UI Not Accessible

Symptoms

Resolution

Permission Issues

Configuration Reset

Best Practices

Do

Don't

Use Cases

Automated Media Downloads

Manual Torrent Management

Private Tracker Seeding

FAQ

Related Applications

Media Management

Indexers

Other Download Clients

Web Interfaces

Additional Resources

Join the Community

2. Connect to `*arr` Applications (Optional)